@sheet Status codes
| Code | Name | What it usually means | Safe to retry as-is? | What an agent should do |
| --- | --- | --- | --- | --- |
| 200 | OK | Request succeeded | n/a | Still check the body: some APIs return 200 with an error object inside |
| 201 | Created | A new resource was created | No | Record the returned ID or Location header; do not create again |
| 202 | Accepted | Queued for processing, not finished | No | Poll the status URL or job ID before reporting success |
| 204 | No Content | Succeeded with no body | n/a | Treat as success; verify the end state if it matters |
| 301 | Moved Permanently | Resource has a new permanent URL | Yes, at the new URL | Follow once and update any stored link |
| 302 | Found | Temporary redirect | Yes, at the new URL | Follow; check the target host is one you expect before sending data |
| 304 | Not Modified | Your cached copy is current | n/a | Use the cached copy |
| 400 | Bad Request | Request was malformed or invalid | No | Read the error message, fix the request, then resubmit |
| 401 | Unauthorized | Missing or invalid credentials | No | Do not guess credentials; report that authentication is needed |
| 403 | Forbidden | Authenticated but not allowed | No | Report the permission gap; do not try other routes around it |
| 404 | Not Found | Nothing at this URL, or hidden from you | No | Check the ID or path; search rather than inventing a URL |
| 405 | Method Not Allowed | Wrong HTTP verb for this endpoint | No | Check the API description for the right method |
| 408 | Request Timeout | Server gave up waiting for the request | Usually | Retry with backoff; for writes, check first whether it landed |
| 409 | Conflict | Clashes with current state (e.g. stale revision) | No | Fetch the latest state, reconcile, then resubmit |
| 410 | Gone | Removed permanently | No | Stop requesting it; update references |
| 412 | Precondition Failed | An If-Match or similar check failed | No | Re-read the resource and base your change on the new version |
| 413 | Content Too Large | Request body exceeds the limit | No | Split or shrink the payload |
| 415 | Unsupported Media Type | Wrong Content-Type | No | Send the format the API expects |
| 422 | Unprocessable Content | Well-formed but rejected (validation, policy) | No | Keep your draft, read the reason, fix and resubmit |
| 429 | Too Many Requests | Rate limited | Yes, later | Honour Retry-After; otherwise exponential backoff with jitter |
| 500 | Internal Server Error | Server-side failure | Reads yes; writes check first | Retry a few times with backoff, then report |
| 502 | Bad Gateway | Upstream server gave a bad response | Reads yes; writes check first | Back off and retry; the write may or may not have happened |
| 503 | Service Unavailable | Overloaded or down for maintenance | Yes, later | Honour Retry-After; back off |
| 504 | Gateway Timeout | Upstream did not respond in time | Reads yes; writes check first | Outcome unknown: look for evidence before retrying a write |
@endsheet