When a request fails, the API returns the error envelope and the SDK throws. This page is the complete, source-traced map of error codes, statuses, and triggers from apps/api/src/error-map.ts and the per-package error constants.

The error envelope#

A failed request returns:

{ "ok": false, "error": "Invalid email or password", "code": "unauthorized" }

• error is a human-readable message. For most 403s it is deliberately the generic string "forbidden" - the API never leaks why a request was denied beyond the machine code.
• code is a stable machine-readable string. Switch on code, not on error.

The root app.notFound (unknown path) and app.onError (unhandled exception) return { ok: false, error } without a code at 404 / 500 respectively.

How the SDK throws#

The SDK core throws a GatekeeperError on any ok !== true response or non-2xx status. Its shape:

In TypeScript it is an Error subclass (instanceof GatekeeperError); in Python it is an Exception subclass. Catch it and branch on code or status.

Status to code#

fail() derives the default code from the status via codeForStatus() (STATUS_TO_CODE in error-map.ts):

Status class reference#

400 bad_request#

The default for any error string not explicitly mapped, plus validation failures. Services convert unexpected thrown exceptions into a generic string, which also falls through to 400.

401 unauthorized#

A credential was presented and it was bad (invalid, revoked, expired), or required and absent.

The decision engine also emits 401 directly for UNAUTHENTICATED (no credential where one is required) and INVALID_CREDENTIAL (presented credential failed to resolve).

402 plan_limit#

An entitlement cap was reached. Route handlers set this explicitly when an entitlement check fails (team members, API keys, or webhooks limit reached). The decision engine maps ENTITLEMENT_EXCEEDED and QUOTA_EXCEEDED to 402.

403 forbidden#

The caller is authenticated but not permitted. The message is almost always the literal "forbidden".

Engine deny reasons that resolve to 403: NOT_A_MEMBER, INSUFFICIENT_ROLE, PERMISSION_DENIED, PLATFORM_PERMISSION_DENIED. Routes that minted a key token from a scopeless key also return 403 explicitly. Note that a NOT_A_MEMBER 403 is remapped to 404 on routes with hideNotFound.

404 not_found#

A resource is absent, or hidden to avoid leaking its existence to non-members.

A hideNotFound route additionally turns a NOT_A_MEMBER 403 into this 404.

409 conflict#

A state conflict - the request is well-formed but collides with existing state.

413 payload_too_large#

The request body exceeds the limit. In practice the payment webhook ingest route caps the body at 256 KiB.

429 rate_limited#

A rate-limit tier was exceeded. The response carries a Retry-After header (seconds), which the SDK parses into GatekeeperError.retryAfter. The engine emits this for the RATE_LIMITED deny reason.

503 service_unavailable#

A dependency faulted and the request was rejected fail-closed. This is never a verdict about the caller; it is retryable.

The decision engine maps every operational fault reason (identity, membership, permission, entitlement, quota, or rate-limiter backend unavailable, plus an internal try/catch) to 503. A backend fault never silently becomes an allow.

Mapping mechanics#

Domain error strings are exact-matched in ERROR_STATUS (error-map.ts); anything unlisted defaults to 400. Because the map keys off each package's exported error constant, renaming a constant is a compile error here rather than a silent status change.