AgentFSRetries and recovery
Decide when an agent should retry, wait, repair its request, or stop.
AgentFS returns errors as application/problem+json. Read status, code, detail, and retryable before choosing the next action. Do not retry an operation merely because it failed.
Decision table
| Response | Meaning | Agent action |
|---|---|---|
400, 401, 403, 404, 409, 412, 413, 422, 451 | The request, credentials, permissions, or current state need attention. | Stop retrying. Read code and detail, then correct the input or ask for access. |
408 | The request took too long to arrive. | Retry with backoff. |
429 | The caller has reached a rate or quota limit. | Wait for Retry-After seconds, then retry. Back off further if it happens again. |
500–599 | AgentFS or its storage dependency could not complete the request. | Retry with backoff. A 503 carries Retry-After; wait at least that long. |
| Network error before a response | The server may have received the request. | Retry only a write that is safe to repeat (see below). |
Retry only these: 408, 429, 5xx, and dropped connections. Every other status fails the same way twice.
Safe writes
For POST /v1/files, set Idempotency-Key to a stable value for one logical upload. Reusing the key with identical bytes returns the first file rather than creating another one. Do not reuse it for different content.
For a path an agent owns, upload with if_exists=replace. Repeating the same byte upload to that path is safe and keeps its file ID and hosted URL.
POST /v1/batch requires Idempotency-Key; preserve it until the batch reaches a terminal state.
Reads (GET) are always safe to retry. So are POST /v1/uploads with the same path and size_bytes (it returns the live session), part uploads, POST /v1/uploads/:id/complete, deletes, and restores. A plain POST /v1/files without Idempotency-Key or if_exists=replace is not: a retry after a lost response can create a second file.
Backoff
Every 429 and 503 carries a Retry-After header in seconds. Wait at least that long before the next attempt.
Otherwise use exponential backoff: wait about 1 second, then double the wait after each failure, and cap it between 30 and 60 seconds. Add random jitter, for example by waiting a random time between zero and the current delay, so agents that failed together do not retry together. Stop after a bounded number of attempts, such as 8.
Never blindly retry a 409: it may mean a path already exists, an ETag precondition failed, a multipart upload has already completed, or an idempotency key was reused for different bytes. Resolve the state first.
Request identity
Pass a unique X-Agent-ID and X-Run-ID on authenticated requests. They make it possible to list the files one run created and to distinguish a retried operation from work started by another agent.
See Errors for every documented problem code and the generated endpoint reference for endpoint-specific request details.