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:

{
  "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 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 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 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, 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), or retention refused to store a MemoryStore 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 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, 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

Quickstart

Drive your first Run end to end and see these error types in context.

API reference

Browse the endpoints and shapes that emit this error envelope.