# Error codes

Every non-2xx body. Two envelopes are live: most routes send `error`
(a sentence) with an optional `code` or `error_code`; the org-wide
session search sends `code` and `message`. Some refusals add fields
(`candidates`, `fields`, plan usage). Branch on `code` / `error_code`.

| Code | Status | Sent by |
| --- | --- | --- |
| `ATTACHMENT_EXPIRED` | 410 | `createSession` |
| `ATTACHMENT_IN_USE` | 409 | `createSession`, `postSessionMessage` |
| `ATTACHMENT_NOT_FOUND` | 404 | `createSession` |
| `ATTACHMENT_NOT_UPLOADED` | 409 | `createSession`, `postSessionMessage` |
| `CANCELLATION_UNCONFIRMED` | 503 | `cancelSession` |
| `CATALOG_REFRESH_REQUIRED` | 409 | `createSession` |
| `COMPUTE_LIMIT_REACHED` | 402 | `createSession` |
| `CONNECTION_AMBIGUOUS` | 422 | `createSession`, `createSavedAgent` |
| `CONNECTION_NOT_READY` | 422 | `createSession`, `createSavedAgent` |
| `CONNECTION_UNAVAILABLE` | 422 | `postSessionMessage` |
| `CONTENT_TOO_LARGE` | 400 | `postSessionMessage` |
| `CONTINUATION_UNSUPPORTED` | 409 | `postSessionMessage` |
| `FIELD_REMOVED` | 400 | `createSession`, `postSessionMessage`, `createSavedAgent` |
| `FORBIDDEN` | 403 | `postSessionMessage` |
| `IDEMPOTENCY_CONFLICT` | 409 | `createSession`, `createSavedAgent` |
| `IF_MATCH_REQUIRED` | 428 | `deleteSavedAgent` |
| `IMMUTABLE_FIELD` | 422 | `updateSavedAgent` |
| `INPUT_FETCH_FAILED` | 422 | `createSession`, `postSessionMessage` |
| `INSTALLATION_NOT_LINKED` | 403 | `createSession` |
| `INVALID_BODY` | 400 | `createSession`, `postSessionMessage`, `createFiles` |
| `INVALID_DESCRIPTION` | 422 | `createSavedAgent` |
| `INVALID_EFFORT` | 422 | `createSavedAgent` |
| `INVALID_FILTER` | 400 | `getSessionMessages` |
| `INVALID_HARNESS` | 422 | `createSavedAgent` |
| `INVALID_INSTRUCTIONS` | 422 | `createSavedAgent` |
| `INVALID_MODEL` | 422 | `createSavedAgent` |
| `INVALID_NAME` | 422 | `createSavedAgent` |
| `MCP_SERVER_URL_INVALID` | 422 | `createSession` |
| `MODEL_UNSUPPORTED` | 422 | `createSession` |
| `NOT_FOUND` | 404 | `getSessionMessages`, `getSavedAgent`, `updateSavedAgent`, `deleteSavedAgent` |
| `PAYMENT_METHOD_REQUIRED` | 402 | `createSession` |
| `PROJECT_PAUSED` | 409 | `postSessionMessage` |
| `RATE_LIMITED` | 429 | `createSession` |
| `REPO_NOT_IN_INSTALLATION` | 403 | `createSession` |
| `REQUEST_TOO_LARGE` | 413 | `createSession`, `postSessionMessage` |
| `RESOURCE_NOT_ACCESSIBLE` | 422 | `createSession` |
| `RESOURCE_UNSUPPORTED` | 422 | `createSession` |
| `RUN_STATE_CONFLICT` | 409 | `cancelSession` |
| `SECRET_DESCRIPTION_INVALID` | 422 | `createSecret`, `updateSecret` |
| `SECRET_FIELD_IMMUTABLE` | 422 | `updateSecret` |
| `SECRET_KIND_INVALID` | 422 | `createSecret` |
| `SECRET_NAME_INVALID` | 422 | `createSecret` |
| `SECRET_NAME_TAKEN` | 409 | `createSecret` |
| `SECRET_NOT_FOUND` | 404 | `updateSecret`, `deleteSecret` |
| `SECRET_PROJECT_NOT_IN_ORG` | 422 | `createSecret` |
| `SECRET_PROJECT_REQUIRED` | 422 | `createSecret` |
| `SECRET_TARGET_INVALID` | 422 | `createSecret` |
| `SECRET_VALUE_INVALID` | 422 | `createSecret`, `updateSecret` |
| `SESSION_NOT_CAPTURED` | 404 | `getSessionMessages` |
| `SKILL_FETCH_FAILED` | 422 | `createSession`, `createSavedAgent` |
| `SKILL_INVALID` | 422 | `createSession`, `createSavedAgent` |
| `SPEND_CAP_REACHED` | 402 | `createSession` |
| `STALE_ETAG` | 412 | `updateSavedAgent`, `deleteSavedAgent` |
| `TASK_TERMINAL` | 409 | `postSessionMessage` |
| `TOKEN_LIMIT_REACHED` | 402 | `createSession` |
| `TOO_MANY_FILES` | 400 | `createFiles` |
| `TURN_ACTIVE` | 409 | `postSessionMessage` |
| `UNKNOWN_FIELD` | 400 | `createSession`, `createSavedAgent` |
| `UNSUPPORTED_AGENT` | 422 | `createSession` |
| `UNSUPPORTED_PROFILE` | 422 | `createSavedAgent` |
| `VALIDATION_ERROR` | 400 | `createApiKey`, `updateApiKeyWebhook` |
| `WEEKLY_COMPUTE_LIMIT_REACHED` | 402 | `createSession` |