Errors

The public state, user state, dev API key, authentication, and rate-limiting pages each document the closed set of statuses and error codes their operations can return. The account and billing pages describe route groups only and carry no per-operation contract. This page describes the shared error envelope, the responses produced by the request pipeline before any operation runs, and the PATCH rejection codes shared by the state endpoints.

Per-operation failures are documented with the operation:

• write precondition failures (412) under Public State - Write Semantics
• quota and tier-limit responses (402) and standard rate limiting (429) under Rate Limiting
• API-key authentication failures (401) under Dev API Keys; wrong-project API keys (403) under Public State
• route validation: an unknown account or project route segment returns 404; an invalid environment value returns 400 (see Environments); a malformed accountId, slug, or env segment returns 400 validation_error naming the segment in message

Error envelope

On 4xx and 5xx, endpoints that return a body use the JSON envelope {"error": "...", "message": "..."}. error is a stable, machine-readable code and is what client code should branch on. message is a human-readable explanation, safe to display but not guaranteed stable across releases; do not match on it. Message text quoted on this site is illustrative only.

There is no single global code set: each operation documents the closed set of codes it can return. On the state endpoints, validation_error is the generic 400 code for body validation failures.

There are four exceptions. POST /v1/auth/token returns the RFC 6749 error shape, {"error": "...", "error_description": "..."}; see Authentication. 402 quota responses carry a quota body with no error field; branch on its code field instead, see Quota responses (402). GET /v1/api-key/info returns 401 with an empty body when the request is not authenticated with a valid API key; see Dev API Keys. Public-state routes called with a valid API key from a different project return 403 with an empty body; see Public State. Check for an empty body before parsing on these responses.

Responses from the request pipeline

These are produced before the operation runs and can therefore occur on any route that reads a request body. They use the envelope above.

• 415 unsupported_media_type: a JSON endpoint received a Content-Type other than application/json.
• 408 request_timeout: the request body was not received in time.
• 413 payload_too_large: the request body exceeded the server's request-size limit.
• 503 service_unavailable: the service is temporarily unavailable. The response carries Retry-After: 5 and the request can be retried unchanged; see Retry-After.

POST /v1/auth/token reads its form itself and answers an RFC 6749 400 invalid_request body instead of 408 or 413.

Patch rejection codes

A rejected PATCH returns 400 with the envelope {"error":"<code>","message":"..."}. Operations apply in order as one atomic write: the first failing operation rejects the whole request and nothing is written. The semantics are identical for user-state PATCH and public-state PATCH.

Supported operations are exactly add, remove, and replace, matched case-sensitively. Paths are RFC 6901 JSON Pointers; the empty string "" targets the document root.

patch_invalid

The request shape itself is wrong: the ops field is missing, the ops array is empty, or a remove targets the document root.

{ "ops": [ { "op": "remove", "path": "" } ] }

patch_unsupported_operation

op is anything other than exactly add, remove, or replace. Matching is case-sensitive, so a differently cased spelling such as Add is rejected:

{ "error": "patch_unsupported_operation", "message": "Unsupported operation 'Add'. Supported operations: add, remove, replace" }

patch_invalid_path

A non-empty path that does not start with /, or an invalid ~ escape; only ~0 (for ~) and ~1 (for /) are valid escapes. The empty-string path is valid and targets the document root.

{ "ops": [ { "op": "add", "path": "foo", "value": "bar" } ] }

patch_missing_value

An add or replace operation without a value field. JSON null counts as a value, so "value": null passes; only an absent value key is rejected. remove never needs a value.

{ "error": "patch_missing_value", "message": "Operation 'replace' requires a value" }

patch_path_not_found

The target location is absent. A replace or remove on an object key that does not exist fails, and a missing intermediate key on an object anywhere in the path fails for every operation. add creates a missing final key, but it does not create missing parents.

{ "ops": [ { "op": "add", "path": "/missing/key", "value": 1 } ] }

patch_path_untraversable

A path segment descends through a value that is not an object or array: a string, number, boolean, or JSON null. This is a type collision, distinct from absence (patch_path_not_found). Given state {"scalar": 5}:

{ "error": "patch_path_untraversable", "message": "Parent path is not an object or array for '/scalar/key'" }

patch_invalid_array_index

Array index segments must be digits only, with no leading zeros. add accepts - or an index up to and including the array length (both append at the end); replace, remove, and intermediate traversal require an index strictly less than the length. Given state {"items": [1, 2]}:

{ "ops": [ { "op": "replace", "path": "/items/2", "value": 3 } ] }

patch_invalid_state_root

The patched result root is not a JSON object, for example an add or replace at path "" with a scalar or array value, or a sub-path operation runs while the current root is not an object.

{ "ops": [ { "op": "replace", "path": "", "value": [] } ] }

patch_state_too_large

The state resulting from the patch exceeds the state size limit stated under Public State - Write Semantics:

{ "error": "patch_state_too_large", "message": "State value exceeds the maximum size of 256,000 characters" }

The same oversize failure on public-state PUT returns validation_error instead; patch_state_too_large applies only to PATCH.

SDK error handling

For how the JavaScript SDKs classify these responses, see SDK Error Handling.