Errors and retries
What each failure means and whether to retry.
Errors use application/problem+json with a stable code and a traceId to quote to us.
| Status | Meaning | Retry? |
|---|---|---|
| 401 | Missing or invalid agent authentication | Only with a new token |
| 403 | Not the bound workload agent, or the scope is missing | No |
| 404 | Not found, or not owned by this agent | No |
| 409 | This idempotency key was used for a different request | No: use a new key |
| 422 | The request or mapping is invalid, or the form is switched off here | No: fix the request |
| 429 | Too many requests | Yes, after Retry-After |
| 503 | A required dependency is unavailable | Yes, with backoff, using the same key |
Always retry with the same key
If a call fails on the network, you don't know whether it arrived. Send the same request with the same Idempotency-Key. You get the same decision, marked replayed, and never a second action. Simultaneous duplicates behave the same way.
Fail closed
Treat anything other than a clear result as not done. An UNKNOWN execution stays unknown until reconciled; don't report it as success.