Error reference

code is the specific reason and is stable enough to switch on. category groups failures, but retry decisions also need the specific code and the operation: not every Google failure is fixed by waiting.message is for a log line or a support ticket: §4.4 requires it never to contain SQL, stack traces, tokens, keys, cell contents or another user's data, so it is safe to display and useless to parse.

• Wait or repair, according to the code: honour Retry-After for rate_limited and google_quota_exceeded. Reauth needs the owner's consent; an inaccessible sheet needs its access repaired. A shared google category does not make these interchangeable.
• Not retryable as sent: validation, auth, not_found. A retry of the identical request produces the identical refusal.
• Do not blindly replay writes after a 500. The contract gives no idempotency-key guarantee. Check whether the write took effect before retrying; report persistent failures.
• The action column below is guidance, not contract. Statuses, code names and categories are §1.2's and §4.4's own.

The status column is §1.2's. Its grouped 422 row says google/validation without assigning a category to each code. This is source notation, not a valid literal ErrorCategoryfrom §4.4; the per-code assignment remains unspecified in that table.

A refusal, end to end

The single-record read below is the documented way to reach operation_not_allowed: §1.3 requires primary_key_column to be configured for that route, and answers 403 when it is not.

curl 'https://sheet.zaber.tech/api/v1/<api-id>/<record>' \
  -H "Authorization: Bearer sz_live_…"

{
  "error": {
    "code": "operation_not_allowed",
    "message": "<the message names the fix: set a primary key, or list and filter>",
    "category": "auth"
  }
}

§4.4 documents the map the dashboard's JSON routes use: the wrapper in src/server/http/internal-route.ts reads a failure through statusFor, which is a lookup in CATEGORY_STATUS with 500 as the fallback for a category the map does not hold.

The two documented exceptions

• forbidden → 403. §4.4 calls this its one carve-out from auth = 401: a valid cookie with an insufficient role must not be reported as a broken cookie.
• method_not_allowed → 405 with Allow. Its category is validation, which the map alone answers 400, and §4.4 states 405 for it in the code table. So the exceptions listed by §4.4 are two, even though the status-mapping row calls forbidden the only carve-out.

/api/internal/** is the signed-in dashboard's surface: session cookie, guards re-checked per route, success serialised as { data: … } with no meta . Its codes share the same category vocabulary as the public API, and §4.4's reuse rule says an internal failure uses an existing code when one fits and a new code only when none does. This table is here for completeness and because §4.4 is where the status map lives — an /api/v1 integration will not receive these. Six code names do appear in both tables (validation_failed, invalid_key, rate_limited, google_sheet_inaccessible, google_reauth_required, internal_error); the Status column below is §4.4's map applied to each category, with the two exceptions §4.4 states by name.

Codes that never cross over

§4.4 closes the list by naming the five codes that belong to the public engine and never appear on /api/internal/**: api_not_found, invalid_range, operation_not_allowed, key_restricted, key_scope_insufficient. If you are handling one of those, you are on /api/v1.

• rate_limited. On /api/v1 §1.2 and §1.4 both put the wait in the Retry-After header, in seconds. Internally, §4.4 has the same number as fields.retry_after so a route and a server action read one value from one place. A /api/v1 caller reads the header.
• google_quota_exceeded. §1.5 says the engine passes Google's own Retry-After through rather than inventing a number — so the header you get is Google's, not ours.

§1.2's 500 row says the message never leaks internals, and §4.4 explains the mechanism: a handler that throws is answered 500 internal_error by the wrapper after the message is logged server-side, the cause is never serialised into the body, and internalError() has no detail field by design. The one documented message is the fixed sentence “The request could not be completed.”

The useful half of that is what §1.5 adds: every request is logged, including 401s and 404s, and logs contain no keys, headers or bodies. So a 500 is not a dead end — it is a row with a timestamp and a duration on it, which is what meta.duration_ms matches, and enough for an owner to find in the dashboard's log view.

• There is no documented error-code catalogue separate from §1.2's table, so this page lists exactly those twenty-one and no more. A code you see that is not here is not part of the contract.
• There is no documented error body for a 2xx, and none for a redirect: §1.2 defines the error envelope as all non-2xx.
• fields is documented in §4.4 for the internal envelope. The public §1.2 error shape shows three members; this page does not add a fourth to /api/v1.
• Per docs/integration-status.md, the public engine's behaviour is recorded on the Measured-versus-asserted board as asserted, not measured. These codes are the contract's, reproduced faithfully; the board says which of them have been seen on a wire.