Retries

Give temporary outages time to recover while controlling how long work keeps trying.

When Retries Happen

Make handlers idempotent so repeated delivery is safe.

Each Step invocation runs as a Work Item. Argyll schedules a retry when that Work Item enters not_completed, recorded by a work_not_completed event. This status covers:

  • Network or transport failures (connection errors, timeouts)
  • Any non-2xx response from the Step endpoint other than the permanent statuses below, including 5xx and 429

These statuses are permanent failures: 400, 401, 403, 404, 405, 406, 410, 411, 413, 414, 415, 422, and 431. If business logic failed permanently, return one of them with application/problem+json.

Script evaluation and preparation errors are permanent. See script failure behavior.

Configuration

Retry behavior is configured in work_config on the Step:

{
  "id": "charge-card",
  "name": "Charge Card",
  "type": "service",
  "http": {
    "invoke": { "endpoint": "https://api.example.com/payments", "timeout": 5000 }
  },
  "work_config": {
    "max_retries": 3,
    "init_backoff": 1000,
    "max_backoff": 30000,
    "backoff_type": "exponential"
  }
}
FieldMeaning
max_retriesMax retry attempts. -1 = unlimited. 0 = use global default
init_backoffInitial delay in milliseconds. 0 = use global default
max_backoffMaximum delay in milliseconds. 0 = use global default
backoff_typefixed, linear, or exponential. Empty = use global default

Steps with max_retries = 0 and empty backoff fields inherit the engine’s global retry defaults set at startup.

Backoff Strategies

  • Fixed: constant delay between every attempt
  • Linear: delay grows by a fixed increment each attempt
  • Exponential: delay doubles each attempt, up to max_backoff

Retry Lifecycle

Each Work Item retries independently until it succeeds, fails permanently, or exhausts its retry budget. For an async action, a 2xx response only acknowledges acceptance. The callback completes the work. The timeout covers the whole attempt, including the wait for that callback. See Async Callbacks.

Compensation Retries

Compensation attempts follow the same retry rules and work_config settings. See Compensation.

Choose a Retry Policy

  • Use fixed backoff for quick retry of unreliable dependencies
  • Use exponential backoff for retryable outages. HTTP 429 is retried
  • Choose max_retries according to how long the caller can wait. Handlers must always be idempotent
  • Return a permanent status such as 422 to mark a permanent business failure and finish the Work Item