Retries

Configure attempts and backoff for retryable Step failures.

When Retries Happen

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)
HTTP 5xx responses from the Step endpoint

HTTP 4xx responses are permanent failures and do not retry. If business logic failed permanently, return a 4xx with application/problem+json.

Configuration

Retry behavior is configured in work_config on the Step:

{
  "id": "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"
  }
}

Field	Meaning
`max_retries`	Max retry attempts. `-1` = unlimited. `0` = use global default
`init_backoff`	Initial delay in milliseconds. `0` = use global default
`max_backoff`	Maximum delay in milliseconds. `0` = use global default
`backoff_type`	`fixed`, `linear`, or `exponential`. Empty = use global default

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

Backoff Strategies

Backoff is the delay before another retry attempt.

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:

graph TD Start["Work item starts"] Execute["Execute step"] Success["2xx response"] Fail4xx["4xx response"] Fail5xx["5xx / transport error"] Retry["Schedule retry
(with backoff)"] Done["Work item complete"] Failed["Work item failed permanently"] Exhausted["Max retries reached"] Start --> Execute Execute --> Success --> Done Execute --> Fail4xx --> Failed Execute --> Fail5xx --> Retry Retry --> Execute Retry -->|"max_retries hit"| Exhausted --> Failed

Compensation Retries

When a Step uses compensated handling, compensation attempts use the same work_config retry settings as normal work. The engine treats 5xx compensation responses as temporary failures and retries after the configured delay. When max_retries is exhausted, the compensation is marked compensation_failed.

See Compensation for full details.

Choose a Retry Policy

Use fixed backoff for quick retry of unreliable dependencies
Use exponential backoff for rate-limited or unstable services
Choose max_retries according to the Step’s idempotency guarantees; larger retry budgets suit handlers keyed by Argyll-Receipt-Token
Return HTTP 4xx to mark a permanent business failure and finish the Work Item