Retry and Dead-Letter Planner

Overview

You send a batch of failures and a retry policy, and we tell you what to do with each one: retry it after a computed delay, or stop and dead-letter it. The decision order is fixed — a terminal error code wins, then a failure you marked non-retryable, then an exhausted attempt budget, and everything else is retried. Delays come from your backoff settings, optionally jittered from a seed you supply, so the same batch always produces the same plan. We compute the plan only: nothing is enqueued, retried, slept on, or written anywhere, and we never look at your queue or the clock.

Retry logic is written once per service and drifts: one worker gives up too early, another hammers a dead upstream, and nobody can explain why a job landed in the dead-letter queue. Putting the decision and the arithmetic in one place makes the policy explicit and the outcome reproducible.

When to use it

Scope

Non-goals

• Does not enqueue, retry, sleep, or dead-letter anything
• Does not read or write your queue, database, or job state
• Does not invent a timestamp — delays are offsets, not wall-clock times
• Does not decide whether an error is retryable for you
• Does not generate random jitter; jitter is derived from your seed

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

How we handle your data

Input schema

Output schema

API contract

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"workflow.retry_dead_letter_plan","input":{"failures":[{"id":"job-1","attempt":2,"errorCode":"UPSTREAM_TIMEOUT","retryable":true}],"policy":{"maxAttempts":5,"backoff":"EXPONENTIAL","baseDelayMs":1000,"maxDelayMs":60000}}}'

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("workflow.retry_dead_letter_plan", {"policy":{"backoff":"EXPONENTIAL","terminalCodes":["SCHEMA_INVALID"],"baseDelayMs":1000,"maxDelayMs":60000,"maxAttempts":5,"multiplier":2},"failures":[{"attempt":2,"errorCode":"UPSTREAM_TIMEOUT","retryable":true,"id":"job-1"},{"attempt":1,"errorCode":"SCHEMA_INVALID","retryable":true,"id":"job-2"},{"attempt":5,"errorCode":"UPSTREAM_TIMEOUT","retryable":true,"id":"job-3"}]});

Errors

Other limits

Limitations

• Does not enqueue, retry, sleep, or dead-letter anything
• Does not read or write your queue, database, or job state
• Does not invent a timestamp — delays are offsets, not wall-clock times
• Does not decide whether an error is retryable for you
• Does not generate random jitter; jitter is derived from your seed
• Executing the retries themselves
• Deciding retryability from the error text
• Scheduling a single job with no policy — a fixed sleep is simpler

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "workflow.retry_dead_letter_plan",
  "input": {
    "policy": {
      "backoff": "EXPONENTIAL",
      "terminalCodes": [
        "SCHEMA_INVALID"
      ],
      "baseDelayMs": 1000,
      "maxDelayMs": 60000,
      "maxAttempts": 5,
      "multiplier": 2
    },
    "failures": [
      {
        "attempt": 2,
        "errorCode": "UPSTREAM_TIMEOUT",
        "retryable": true,
        "id": "job-1"
      },
      {
        "attempt": 1,
        "errorCode": "SCHEMA_INVALID",
        "retryable": true,
        "id": "job-2"
      },
      {
        "attempt": 5,
        "errorCode": "UPSTREAM_TIMEOUT",
        "retryable": true,
        "id": "job-3"
      }
    ]
  }
}

Examples

{
  "policy": {
    "backoff": "EXPONENTIAL",
    "terminalCodes": [
      "SCHEMA_INVALID"
    ],
    "baseDelayMs": 1000,
    "maxDelayMs": 60000,
    "maxAttempts": 5,
    "multiplier": 2
  },
  "failures": [
    {
      "attempt": 2,
      "errorCode": "UPSTREAM_TIMEOUT",
      "retryable": true,
      "id": "job-1"
    },
    {
      "attempt": 1,
      "errorCode": "SCHEMA_INVALID",
      "retryable": true,
      "id": "job-2"
    },
    {
      "attempt": 5,
      "errorCode": "UPSTREAM_TIMEOUT",
      "retryable": true,
      "id": "job-3"
    }
  ]
}

{
  "_meta": {
    "delaysFloored": 0,
    "delaysCapped": 0
  },
  "actions": [
    {
      "id": "job-1",
      "reasonCode": "RETRY_SCHEDULED",
      "action": "RETRY",
      "nextAttempt": 3,
      "delayMs": 2000,
      "retryAtOffsetMs": 3000
    },
    {
      "id": "job-2",
      "reasonCode": "TERMINAL_CODE",
      "action": "DEAD_LETTER",
      "nextAttempt": 0,
      "delayMs": 0,
      "retryAtOffsetMs": 0
    },
    {
      "id": "job-3",
      "reasonCode": "ATTEMPTS_EXHAUSTED",
      "action": "DEAD_LETTER",
      "nextAttempt": 0,
      "delayMs": 0,
      "retryAtOffsetMs": 0
    }
  ],
  "summary": {
    "total": 3,
    "retry": 1,
    "deadLetter": 2,
    "terminalCode": 1,
    "notRetryable": 0,
    "attemptsExhausted": 1
  },
  "policy": {
    "maxAttempts": 5,
    "backoff": "EXPONENTIAL",
    "baseDelayMs": 1000,
    "maxDelayMs": 60000,
    "multiplier": 2,
    "jitter": "NONE",
    "jitterPercent": 0
  }
}

{
  "policy": {
    "maxDelayMs": 60000,
    "backoff": "FIXED",
    "baseDelayMs": 5000,
    "maxAttempts": 4
  },
  "failures": [
    {
      "id": "webhook-42",
      "errorCode": "RATE_LIMITED",
      "retryable": true,
      "attempt": 1,
      "retryAfterMs": 30000
    }
  ]
}

{
  "_meta": {
    "delaysFloored": 1,
    "delaysCapped": 0
  },
  "actions": [
    {
      "id": "webhook-42",
      "reasonCode": "RETRY_SCHEDULED",
      "action": "RETRY",
      "nextAttempt": 2,
      "delayMs": 30000,
      "retryAtOffsetMs": 30000
    }
  ],
  "summary": {
    "total": 1,
    "retry": 1,
    "deadLetter": 0,
    "terminalCode": 0,
    "notRetryable": 0,
    "attemptsExhausted": 0
  },
  "policy": {
    "maxAttempts": 4,
    "backoff": "FIXED",
    "baseDelayMs": 5000,
    "maxDelayMs": 60000,
    "multiplier": 1,
    "jitter": "NONE",
    "jitterPercent": 0
  }
}

Recommended use cases

• Turn a batch of failed jobs into a retry schedule your worker can act on
• Apply one shared, auditable retry policy across several services
• Spread retries with reproducible jitter so a whole batch does not wake up together

Avoid for

• Executing the retries themselves
• Deciding retryability from the error text
• Scheduling a single job with no policy — a fixed sleep is simpler

Related skills

Composable with

Safety & privacy

• Runs without calling any external service.
• Your payloads are never stored permanently.
• Telemetry captures metadata only — never your payload contents.
• We never train models on your payloads.
• No human reviews your payloads.

Tags