> ## Documentation Index
> Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> Handle Checkfu's stable typed error envelope and retry only what is safe to retry.
Every versioned JSON error uses the same typed envelope:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"error": {
"type": "runtime.invalid_transition",
"message": "cannot drive a terminal session",
"more": "https://docs.checkfu.com/reference/errors#runtime-invalid-transition"
}
}
```
Switch on `error.type`, not on the human-readable message. Messages are written for humans and may be reworded; the type is contract. Every error includes a stable `more` URL that links directly to its catalog entry. A documented type can add structured recovery data inside `error`; for example, `validation.prompt_integrity_review_required` adds a `review` challenge. The same envelope is returned across every endpoint, including [Session and Run](/concepts/sessions-and-runs) operations.
## Namespaces
The prefix tells you who has to act.
| Namespace | Meaning | Who resolves it |
| ------------ | ------------------------------------------------------------------- | ----------------------------- |
| `validation` | The request is malformed, missing, conflicting, or too large. | The caller |
| `auth` | The API key is missing, unknown, revoked, or wrong-scope. | The caller |
| `policy` | Governance denied the action. | A Workspace administrator |
| `budget` | A capacity ceiling was reached. | A Workspace administrator |
| `billing` | Commercial entitlement blocks Checkfu-funded work. | An Organization administrator |
| `model` | Model routing or provider credentials failed. | A Workspace administrator |
| `memory` | A MemoryStore or document operation failed. | Varies |
| `runtime` | Execution machinery failed, or was asked for an illegal transition. | Usually Checkfu |
User-correctable errors carry enough detail to fix the request, so a model driving the API can self-correct. Internal failures return an opaque incident reference instead of a stack trace or secret-bearing context.
## Error registry
| Type | HTTP | Safe to retry |
| ------------------------------------------------------------------------------------------------------ | ---: | ------------- |
| validation.malformed | 400 | No |
| validation.prompt\_integrity\_review\_required | 400 | No |
| validation.not\_found | 404 | No |
| validation.conflict | 409 | No |
| validation.idempotency\_conflict | 409 | No |
| validation.idempotency\_in\_progress | 409 | Yes |
| validation.payload\_too\_large | 413 | No |
| validation.range\_too\_large | 422 | No |
| auth.invalid\_key | 401 | No |
| auth.disabled\_tenancy | 403 | No |
| policy.denied | 403 | No |
| budget.exceeded | 429 | No |
| model.no\_eligible\_model | 422 | No |
| model.credential\_rejected | 422 | No |
| model.platform\_supply\_unavailable | 503 | Yes |
| model.platform\_capacity\_reached | 503 | Yes |
| billing.entitlement\_unavailable | 503 | Yes |
| billing.usage\_limit\_reached | 402 | No |
| billing.payment\_required | 402 | No |
| billing.seat\_activation\_unavailable | 503 | Yes |
| memory.not\_found | 404 | No |
| memory.conflict | 409 | No |
| memory.read\_only | 403 | No |
| memory.invalid\_path | 400 | No |
| memory.backend\_unavailable | 503 | Yes |
| memory.curation\_failed | 422 | No |
| runtime.invalid\_transition | 409 | No |
| runtime.primary\_thread | 409 | No |
| runtime.checkpoint\_expired | 409 | No |
| runtime.session\_history\_unavailable | 409 | No |
| runtime.harness\_unavailable | 503 | Yes |
| runtime.harness\_failed | 502 | Yes |
| runtime.runner\_unavailable | 503 | Yes |
| runtime.lease\_lost | 409 | No |
| runtime.start\_timeout | 503 | Yes |
| runtime.provisioning\_suspended | 503 | Yes |
| runtime.turn\_deadline\_exceeded | 504 | No |
| runtime.observation\_gap | 409 | Yes |
| runtime.observation\_conflict | 409 | No |
| runtime.attestation\_invalid | 400 | No |
| runtime.harness\_incompatible | 422 | No |
| runtime.internal | 500 | Yes |
`validation.payload_too_large` always names a specific documented ceiling. [Request and payload limits](/reference/lookup#request-and-payload-limits) lists every one of them, and which of them refuse with a `413` rather than a `400`.
`validation.range_too_large` is its read-side counterpart, and the distinction is worth holding: the request is well formed, but your Workspace's data density exceeds what the read can decode. It is never a truncated answer. Whether a narrower range fixes it depends on which read you called, and the message says which case you are in — a **grouped** read replays the whole requested range, so narrowing works, while the **Workspace-total** read replays a roughly 48-hour tail anchored to `as_of` rather than to your request, so narrowing does not reduce it.
`runtime.attestation_invalid` appears only on the connected-runtime observation path: a signed observation batch whose Ed25519 signature, runtime registration, or placement does not verify. Ordinary API clients never produce it.
`runtime.provisioning_suspended` settles a Run after several consecutive provisioning failures in a short window: the sandbox provider kept refusing or never became ready, so the platform stops burning provider attempts for a short cooldown instead of retrying forever. It clears itself — the next Run after the cooldown provisions normally, and a single successful start resets the count.
## Retry guidance
Retry only the types marked **Yes** above.
Retry those with exponential backoff and jitter, capping the number of attempts. Everything else is a decision, not a transient failure: the request, the configuration, or an approval has to change before it can succeed. Retrying a `policy.denied` or a `runtime.invalid_transition` fails identically every time.
Three retryable types are worth calling out because they are easy to misread:
* `validation.idempotency_in_progress` means another request carrying the same `Idempotency-Key` is still in flight. Back off and retry the identical request; you receive the first request's result rather than causing a second mutation.
* `runtime.observation_gap` means execution evidence arrived out of order. The Run is intact and the write is safely repeatable.
* `memory.backend_unavailable` means the versioned [MemoryStore](/concepts/memory) backend cannot serve the operation and the write was not applied. When an enabled backend is unhealthy, back off and retry. In the hosted alpha the versioned surface is intentionally disabled pending D7, so retries cannot make those fenced endpoints succeed. A document body that retention refuses is a different answer entirely: it returns `403 policy.denied`, never this type, so no amount of retrying stores it.
`memory.read_only` is never retryable, and one of its causes is easy to mistake for a race: a write against an **archived** MemoryStore returns `403 memory.read_only`, not a `409`. Archiving is not a transient state, so retrying never clears it.
## Errors that need an upstream change
| Type | What actually happened |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `budget.exceeded` | Some capacity ceiling was reached: a customer-configured [Budget](/concepts/automations), a Workspace monthly quota, a ToolInvocation ceiling, or an API-key rate limit. It does **not** specifically mean a Budget resource was breached. |
| `billing.payment_required` | The Organization's payment is past due. Reads, exports, and login continue; new Checkfu-funded work does not. |
| `billing.usage_limit_reached` | Commercial entitlement is exhausted. Distinct from `budget.exceeded`, which is a self-imposed customer limit. |
| `policy.denied` | Either governance returned `deny` (no PermissionAssignment matched, or an ActionPolicy rule denied it; see [Tenancy and governance](/concepts/tenancy-and-governance)), or retention refused to store a [MemoryStore](/concepts/memory) document body: the Workspace is zero-data-retention, or the content's retention ceiling has already elapsed. Both are settled answers, not races. |
| `model.no_eligible_model` | Every candidate in the [ModelRoutingProfile](/concepts/harnesses-and-models) violated a Workspace provider constraint. Routing fails closed rather than silently choosing a disallowed model. |
| `model.credential_rejected` | A Workspace provider key was present but rejected. An invalid override never falls back to platform supply. |
| `validation.idempotency_conflict` | The same `Idempotency-Key` was reused with a **different** request body. |
## CLI exit codes
Scripted callers get a stable, closed **failure-class** axis: the CLI maps every error to one process exit code, keyed on the kind of failure rather than the specific `error.type`. This lets a script branch on `$?` without parsing JSON.
| Exit | Class | Covers |
| ---- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0` | success | No failure |
| `1` | usage | `400` request-shape or review errors (`validation.malformed`, `validation.prompt_integrity_review_required`), any other unmapped `4xx` including `413 validation.payload_too_large`, bad CLI invocation, or a domain-outcome failure the transport delivered successfully |
| `2` | network | Transport failure reaching the API |
| `3` | auth | `401`/`403`: `auth.invalid_key`, `policy.denied` |
| `4` | not\_found | `404 validation.not_found` |
| `5` | conflict | `409` conflicts (`validation.idempotency_conflict`, `runtime.invalid_transition`, …) |
| `6` | invalid | `422` unprocessable: a semantically valid shape the platform can't act on (`model.no_eligible_model`, `runtime.harness_incompatible`, `memory.curation_failed`) |
| `7` | rate\_limited | `429 budget.exceeded` |
| `8` | server | `5xx` |
| `9` | billing | `402`: `billing.payment_required`, `billing.usage_limit_reached` |
`130` and `143` are reserved for `SIGINT`/`SIGTERM`. Exit codes signal the *kind* of failure only. A run's actual result still comes from the [event log](/reference/events), and a task that ran but failed its rubric is a successful transport (exit `1` as a usage-level outcome), not a transport error.
## Next steps
Drive your first Run end to end and see these error types in context.
Browse the endpoints and shapes that emit this error envelope.