Error codes

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/reason

The 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

FieldReaches a clientWhat it is
codeYesStable, and the thing to branch on
messageYesThe problem, in English, permanently
paramsYesStructured values a translating client interpolates
actionNoThe operator’s remedy. Stripped by the HTTP codec
detailNoInternal 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

StatusDo
400Fix the request. Retrying identically will not help
401Sign in again. A mobile client rotates before its session expires, so a 401 means the session is gone
402The plan’s allowance is used up. The remedy is a purchase, a bigger tier, or a number pinned for this customer
403Do not retry. The caller is who they say and may not do this
404It is not there
409A conflict — usually a state that moved under you
410Gone, permanently
413Too large
429Back off
5xxThe 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

CodeMeaning
validation/invalid_inputInput failed validation at a boundary. Carries the failing issues, so a form can highlight the field
input/requiredA 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_foundThe requested resource does not exist
core/conflictThe state moved under you
core/precondition_failedSomething the call depends on is missing. The CLI’s line names the command that fixes it, when it knows one
core/person_requiredA step only a person may take — a typed confirmation phrase, or pithy remove. Stop and ask, rather than trying variations
core/internalA fault in the deployment
core/upstream_failed, core/upstream_timeoutA third party did not answer, or answered wrongly
core/webhook_unverifiedThe sender’s proof did not check out
core/workflow_failed, core/unknown_workflow, core/invalid_workflow_params, core/missing_workflow_bindingDurable-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_configuredOutbound, from the CLI or CI. Never from a request handler

Auth

CodeStatusMeaning
auth/invalid_token401The credential is missing, expired or invalid
auth/forbidden403Authenticated, and not allowed to do this
auth/recent_sign_in_required403Signed 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_fresh403Signed 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_suspended403The account is suspended. The operator’s reason is the message, and params.suspendedUntil names the end when there is one
auth/account_deleted403The account is deleted and inside its purge window. params.purgeAfter names the last day it can be restored
auth/handoff_invalid400The 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_missing400A send route wanted a native app attestation and got none: the environment has an attestation block and turnstile is not composed
auth/attestation_failed403The 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_config500The 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_unavailable503An 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

CodeStatusMeaning
organization/not_found404That organization does not exist
organization/forbidden403The member’s role does not allow that
organization/organization_suspended403An 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_catalog400The role catalog is not valid. It names the catalog, not the request
organization/invitation_invalid400The invitation can no longer be accepted
organization/nomination_invalid400There is no offer of ownership for this caller to accept
organization/last_administrator409The write would leave nobody who can administer the account
organization/last_owner409An operator’s write would remove or demote the only owner. params.ownershipRoute names the route that moves ownership
organization/already_member409An operator tried to add somebody already in the account. params.role names the role they hold
organization/seat_limit_reached409The account is at its seat limit, which params.seatLimit names
organization/slug_taken409Another account holds that short name
organization/idempotency_key_reused409A 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/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

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.

ESC