# 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.