The grammar
Errors is why a payload carries a code rather than a sentence, English fallback is what a client renders when it has no words for one, and exit codes is the same contract at the CLI.
domain/reasonThe domain is the capability’s own name — the same segment that prefixes its tables and namespaces its migrations, which is what makes one capability’s codes incapable of colliding with another’s.
The code is the discriminator, and the taxonomy is closed. The kit’s codes are a union, each status is pinned to the one it maps to, and a mismatched pair fails validation rather than shipping.
Four fields, two of which cross the wire
| Field | Reaches a client | What it is |
|---|---|---|
code | Yes | Stable, and the thing to branch on |
message | Yes | The problem, in English, permanently |
params | Yes | Structured values a translating client interpolates |
action | No | The operator’s remedy. Stripped by the HTTP codec |
detail | No | Internal context for logs and audit. Stripped |
The code is already the translation key, so a locale file for the kit’s errors is exactly a file that covers these codes — and there is no second identifier to keep in sync.
What a status means to a client
| Status | Do |
|---|---|
| 400 | Fix the request. Retrying identically will not help |
| 401 | Sign in again. A mobile client rotates before its session expires, so a 401 means the session is gone |
| 402 | The plan’s allowance is used up. The remedy is a purchase, a bigger tier, or a number pinned for this customer |
| 403 | Do not retry. The caller is who they say and may not do this |
| 404 | It is not there |
| 409 | A conflict — usually a state that moved under you |
| 410 | Gone, permanently |
| 413 | Too large |
| 429 | Back off |
| 5xx | The deployment is at fault. Retry with backoff, and page somebody |
401 and 403 are the pair worth separating. A client that treats them the same loops: it signs in or rotates a perfectly good session, gets another 403, and goes round again.
Core, and the cross-cutting domains
| Code | Meaning |
|---|---|
validation/invalid_input | Input failed validation at a boundary. Carries the failing issues, so a form can highlight the field |
input/required | A question the CLI could not ask, because the run may not prompt. Names the flag that answers it, and the values it takes when the set is known |
core/not_found | The requested resource does not exist |
core/conflict | The state moved under you |
core/precondition_failed | Something the call depends on is missing. The CLI’s line names the command that fixes it, when it knows one |
core/person_required | A step only a person may take — a typed confirmation phrase, or pithy remove. Stop and ask, rather than trying variations |
core/internal | A fault in the deployment |
core/upstream_failed, core/upstream_timeout | A third party did not answer, or answered wrongly |
core/webhook_unverified | The sender’s proof did not check out |
core/workflow_failed, core/unknown_workflow, core/invalid_workflow_params, core/missing_workflow_binding | Durable-job faults. The last one is the first-run surprise — a Workflow binding to a host nothing has provisioned |
cloudflare/request_failed, cloudflare/invalid_response, cloudflare/not_configured | Outbound, from the CLI or CI. Never from a request handler |
Auth
| Code | Status | Meaning |
|---|---|---|
auth/invalid_token | 401 | The credential is missing, expired or invalid |
auth/forbidden | 403 | Authenticated, and not allowed to do this |
auth/recent_sign_in_required | 403 | Signed in, but not recently enough for this route, which the app gated with requireRecentSignIn. The window is the app’s, per route. Sign in again, then retry. Nothing was changed |
auth/session_not_fresh | 403 | Signed in, but not within the last fifteen minutes, on connecting or disconnecting a sign-in provider. Sign in again, then retry. Nothing was changed |
auth/account_suspended | 403 | The account is suspended. The operator’s reason is the message, and params.suspendedUntil names the end when there is one |
auth/account_deleted | 403 | The account is deleted and inside its purge window. params.purgeAfter names the last day it can be restored |
auth/handoff_invalid | 400 | The one-time code a native app trades after a redirect sign-in is spent, expired, unknown, or came with the wrong verifier. One code for all four, and any attempt spends the code. Sign in again |
auth/attestation_missing | 400 | A send route wanted a native app attestation and got none: the environment has an attestation block and turnstile is not composed |
auth/attestation_failed | 403 | The attestation did not verify: a header that does not decode, a challenge stale, reused or never issued, an app not allowed, an App Attest key that does not register, an assertion whose signature or counter does not check out, a Play Integrity verdict that fails, or the test assertion where it is not accepted. It never falls through to Turnstile. Ask for a new challenge |
auth/attestation_config | 500 | The server cannot judge the attestation: the environment has no attestation block, no verifier for the platform, or the Play Integrity service account is missing or refused by Google |
auth/provider_unavailable | 503 | An enabled social provider’s credential would not resolve. Every other sign-in method still works |
That last one is deliberately not a 404: a provider nobody enabled answers a 404, and nobody enabled this and this is broken right now are different facts that must never share an answer.
The two account codes are 403, not 401, because signing in again cannot help. A rotation that answers either one sends the reader to the screen for that state. Suspended and deleted accounts has the rest. auth/handoff_invalid is 400, not 401, because no credential was presented to refuse; sign in on iOS and Android has the trade it answers.
The two recent-sign-in codes are the 403s where signing in again does help, and a rotation does not: a rotated session keeps the sign-in time of the one it replaces. Each is a separate code from auth/forbidden because its remedy is specific and cheap. Require a recent sign-in has the gate and how a web and a phone client answer it.
The three attestation codes answer the send routes when a native app attests in place of a Turnstile token, and the App Attest key route. auth/attestation_config is a 500 because the fault is the deployment’s, not the app’s, and its detail says which. A refusal’s detail starts with the check that failed, such as chain, signature or counter for App Attest, or appRecognitionVerdict or deviceIntegrity for Play Integrity. Google failing to answer a Play Integrity decode is not one of the three: it is core/upstream_failed, or core/upstream_timeout past ten seconds. Native app attestation has the flow for each platform.
Organization
| Code | Status | Meaning |
|---|---|---|
organization/not_found | 404 | That organization does not exist |
organization/forbidden | 403 | The member’s role does not allow that |
organization/organization_suspended | 403 | An operator suspended the organization, so nobody can act in it. The caller’s own account is not affected. params.suspendedUntil names when it ends, when it does |
organization/invalid_role_catalog | 400 | The role catalog is not valid. It names the catalog, not the request |
organization/invitation_invalid | 400 | The invitation can no longer be accepted |
organization/nomination_invalid | 400 | There is no offer of ownership for this caller to accept |
organization/last_administrator | 409 | The write would leave nobody who can administer the account |
organization/last_owner | 409 | An operator’s write would remove or demote the only owner. params.ownershipRoute names the route that moves ownership |
organization/already_member | 409 | An operator tried to add somebody already in the account. params.role names the role they hold |
organization/seat_limit_reached | 409 | The account is at its seat limit, which params.seatLimit names |
organization/slug_taken | 409 | Another account holds that short name |
organization/idempotency_key_reused | 409 | A founding repeated an idempotency key the same person already founded an account with, asking for a different name or short name. Send a new key, or repeat the original request |
The way out of last_owner is a different route from the way out of last_administrator. The last administrator is repaired by promoting somebody; the last owner by forcing ownership onto somebody else, which is why the refusal names the ownership route. seat_limit_reached refuses an invitation accepted against a full account too, and the offer stays pending until a seat frees. An operator’s add may override the limit on purpose, and the override is audited. The organization reference says which route raises each, and the codes from other domains those routes return.
Payments
payments/invalid_receipt · payments/verification_failed · payments/webhook_unverified · payments/environment_mismatch · payments/receipt_already_owned · payments/product_not_found · payments/rail_not_configured · payments/reconcile_not_provisioned · payments/provider_unavailable · payments/subject_unresolved · payments/entitlement_required · payments/entitlement_not_in_catalog · payments/subscription_change_refused · payments/discount_invalid · payments/clawback_failed · payments/override_stale · payments/quota_exceeded
payments/environment_mismatch is the sandbox guard: a purchase whose store environment does not match this deployment’s is refused outright.
payments/entitlement_not_in_catalog is what a grant of a key the entitlements map does not declare gets — because a grant nothing declared is a grant nobody reviewed.
payments/quota_exceeded (402) is an enforced meter at its limit: emails enqueued, bytes stored or media items held would pass the subject’s effective quota for the period, and nothing was written. A meter refuses and never bills. Tiers, quotas and features says when one is enforced.
payments/override_stale (409) is an override write that named a version behind the subject’s row: somebody changed that customer’s allowance after you read it. Nothing was written. Read again, and set against the new version.
Storage
storage/not_found · storage/forbidden · storage/quota_exceeded · storage/upload_incomplete · storage/multipart_failed · storage/share_expired · storage/share_revoked
An object you may not see answers not-found rather than forbidden, because a 403 confirms the object exists. storage/forbidden is only ever a file you can already see and may not change.
storage/quota_exceeded (413) is the configured bytesPerOwner ceiling. Where payments enforces the storageBytes meter, the same refusal is payments/quota_exceeded (402) instead.
Artifacts
artifacts/not_found · artifacts/forbidden · artifacts/invalid_name · artifacts/name_taken · artifacts/invalid_config
artifacts/not_found is one answer for two facts: no such repository, and one the caller neither owns nor holds a grant on. Byte for byte, because the name is in the clone URL. It is also the mint route’s answer for a repository with remote access off. artifacts/forbidden is only ever a repository the caller can already see.
artifacts/invalid_config is raised at boot: a tokenTtlSeconds outside 60 to 3600, or organization composed with no managePower, or one the role catalog does not declare.
Consent
consent/unknown_purpose · consent/stale_notice · consent/method_below_minimum · consent/withdrawal_below_grant · consent/evidence_missing · consent/expiry_passed · consent/document_not_found · consent/evidence_store_missing
consent/stale_notice (409) means the person has to read the notice again: the grant named a notice version that is no longer the purpose’s current one. consent/method_below_minimum and consent/withdrawal_below_grant are both 400, and both mean the same thing to a client: collect a stronger signature. consent/document_not_found is also the answer to a person asking for a document their own record does not name. consent/evidence_store_missing (500) is the one that is yours to fix: bind the CONSENT_EVIDENCE bucket. The consent reference has each one.
email/template_not_found · email/invalid_payload · email/invalid_token · email/rate_limited · email/send_failed · email/suppressed
email/suppressed is not a failure to fix. The address is on the opt-out list, and that is the list working.
Secrets
secrets/not_found · secrets/already_exists · secrets/invalid_value · secrets/crypto_failed · secrets/rotation_unsupported · secrets/rotation_unrecorded
secrets/crypto_failed is what a name mismatch looks like — a ciphertext moved between rows does not open, which turns a query bug into a clean failure rather than a disclosure.
secrets/rotation_unrecorded exits 5, the code for a step that needs a person, and it is the one failure the command cannot undo.
Control plane
controlplane/not_connected · controlplane/invalid_credential · controlplane/insufficient_scope · controlplane/key_not_found · controlplane/key_conflict
controlplane/not_connected is the shipped, denying state rather than a fault.
Turnstile
turnstile/missing_token · turnstile/failed · turnstile/config · turnstile/analytics_window · turnstile/analytics_unavailable · turnstile/analytics_forbidden
A wrong secret is turnstile/config, a 500 — not a failed challenge. A 403 would send whoever is debugging it to look at the user, which is the wrong person and an hour gone. The three analytics codes answer the control-plane widget read: turnstile/analytics_window (400) is a window past what Cloudflare keeps, or wider than one read may ask for, and names the cap; turnstile/analytics_unavailable (409) is an account Cloudflare serves no Turnstile analytics to — a different fact from nothing having been challenged; turnstile/analytics_forbidden (409) is the Worker’s own runtime token lacking Account Analytics Read, which params.permission names, with the rotate that adds it in the message.
Vector
vector/index_not_found · vector/unfilterable_field · vector/metadata_index_drift · vector/dimension_mismatch · vector/metadata_too_large · vector/filter_too_large · vector/topk_exceeded
vector/metadata_index_drift is the boot refusal — the config declares a filterable field the provisioning record does not have.
Ledger
ledger/insufficient_funds · ledger/invalid_amount · ledger/account_not_found · ledger/currency_not_found · ledger/hold_not_found · ledger/hold_not_open · ledger/entry_not_found · ledger/entry_not_reversible · ledger/ref_conflict
ledger/insufficient_funds comes from a database constraint, not from a check in a handler — so it holds under concurrency.
The last three answer a reversal and a management write. ledger/entry_not_found (404) is no entry with that ref on the account named, and an entry on another account answers the same. ledger/entry_not_reversible (409) is an entry of a kind that does not reverse: only a credit or a debit does, and never one that is itself a reversal; params.kind names the kind. ledger/ref_conflict (409) is a ref another entry already holds, so the write is neither recorded nor a replay. Nothing moves on any of them.
Games
Multiplayer: multiplayer/session_not_found · multiplayer/game_not_found · multiplayer/not_a_member · multiplayer/session_full · multiplayer/invalid_move · multiplayer/invalid_transition
Matchmaking: matchmaking/room_not_found · matchmaking/room_full · matchmaking/invalid_code · matchmaking/invite_not_found · matchmaking/invite_forbidden · matchmaking/already_friends · matchmaking/friend_request_not_found · matchmaking/user_not_found · matchmaking/not_queued
Rating: rating/game_not_found · rating/pool_not_found · rating/record_forbidden · rating/unknown_algorithm · rating/unsupported_player_count · rating/invalid_params
Leaderboard: leaderboard/board_not_found · leaderboard/entry_not_found · leaderboard/board_immutable · leaderboard/invalid_schedule · leaderboard/score_rejected · leaderboard/submit_forbidden
rating/unsupported_player_count fails on deploy rather than at the first result — a 1v1 algorithm wired to a four-player game is caught before it produces a month of nonsense.
Media, support, testers, audit
Media: media/not_found · media/forbidden · media/unsupported · media/storage_failed · media/enrichment_failed · media/analytics_window · media/analytics_unavailable · media/analytics_forbidden. Like storage, a record you may not see is media/not_found, and media/forbidden is one you can see and may not change. The three analytics codes answer the delivery read: media/analytics_window (400) is a window past what Cloudflare keeps, or wider than one read may ask for, and names the cap; media/analytics_unavailable (409) is an account whose Customer Metadata Boundary is outside the US, where Cloudflare serves no Stream or Images analytics — a different fact from nothing having been watched; media/analytics_forbidden (409) is the Worker’s own runtime token lacking Account Analytics Read, which params.permission names, with the rotate that adds it in the message. Both analytics_forbidden codes are 409, not 403: the caller’s control-plane credential is fine, and it is the account’s own token that rules the read out.
Support: support/not_found · support/invalid_category · support/rejected · support/unparseable_message · support/classification_failed · support/reply_failed
Testers: testers/not_configured · testers/cohort_not_found · testers/cohort_closed · testers/member_not_found · testers/already_on_roster · testers/withdrawn · testers/roster_full · testers/invalid_token · testers/nudge_cooldown · testers/copy_not_allowed
Audit: audit/invalid_event · audit/write_failed
audit/write_failed never fails the audited action. It is logged and the action proceeds — an audit trail that can take your login down is worse than one with a gap in it.
Where this list comes from
The closed union in @pithy-sh/core’s error payload, plus each capability’s own error module. Those are the authority; this page is a hand-maintained rendering of them.