Errors

Every non-2xx response uses the same envelope. Agents branch on error.type (a stable 10-value enum); each error carries nextActions[] — concrete steps to surface to the user.

Envelope shape

{
  "error": {
    "type": "rate_limited",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded (rpm_exceeded). Retry after 23s.",
    "doc": "https://docs.mareaalcalina.com/concepts/rate-limits",
    "param": null,
    "requestId": "req_30a9358b-70bd-44f3-aa5d-8983b558ad84",
    "requestLogUrl": "https://...",
    "recoverable": true,
    "retryAfterMs": 23000,
    "nextActions": [
      { "label": "Wait 23s and retry the same request.", "method": null, "url": null }
    ],
    "upgrade": null
  }
}

Field guarantees

Field	Type	Notes
`type`	enum (10 values)	Stable. Agents branch on this. See the table below.
`code`	string	Stable, machine-readable. Finer-grained than `type`.
`message`	string	Human-readable. Localized via `Accept-Language`. Do not branch on it.
`doc`	string	Link to the relevant docs page for this code.
`param`	string \| `null`	Name of the offending field (`null` if not field-specific). Never missing.
`requestId`	string	`req_<uuid>` — surface to the user when reporting bugs.
`requestLogUrl`	string	Internal log URL (operator-only).
`recoverable`	boolean	`true` means a retry is meaningful (with appropriate changes).
`retryAfterMs`	integer \| `null`	When set, also returned as the `Retry-After` header (in seconds).
`nextActions`	array	Always an array (possibly empty). `null` is not allowed. Each entry: `{ label, method, url }`.
`upgrade`	object \| `null`	`{ currentPlan, requiredPlan, upgradeUrl, previewUrl? }`. Set only on `plan_limit` errors.
`requiredScopes`	string[] (optional)	Present only when the failure is a scope mismatch.
`heldScopes`	string[] (optional)	Present only when the failure is a scope mismatch.

The 10 error types

`type`	Typical HTTP	When it happens	Agent action
`rate_limited`	429	rpm or rpd quota exceeded	Read `retryAfterMs`, sleep, retry. `recoverable: true`. See Rate limits.
`invalid_request`	400 / 410 / 422	Malformed body, invalid `Idempotency-Key`, oversize snapshot, empty publish	Fix the body and reissue. Do not retry the exact same request.
`auth`	401 / 403	Missing / invalid / revoked key, missing scope	401 → fix credential. 403 with `requiredScopes` → request an upscoped key.
`not_found`	404	Resource missing OR cross-tenant access (silent denial)	Confirm the id is correct AND the key owns it.
`plan_limit`	402	Plan ceiling hit (publish blocked, product cap exceeded)	Surface `upgrade.upgradeUrl` to the user as a CTA. See Plan limits.
`internal`	500	Server bug	Surface `requestId`. Retry once with backoff, then escalate.
`conflict`	409	`Idempotency-Key` in flight (same key still processing)	Wait `retryAfterMs` and retry with the same key.
`idempotency_conflict`	409	Same `Idempotency-Key` reused with a different body	Generate a NEW `Idempotency-Key`. See Safe mutations.
`service_unavailable`	503	Dependency outage or feature flag off	Retry with exponential backoff.
`tos_not_accepted`	451	Calling user has not accepted the Terms of Service	Surface `nextActions[0]` (dashboard link). User must accept; agent cannot bypass. See ToS jurisdiction.

Recovery matrix

If `error.type` is	Surface to user?	Retry?	What to do
`rate_limited`	No (transparent)	Yes after `retryAfterMs`	Sleep + retry same request + same `Idempotency-Key`
`invalid_request`	No (fix client-side)	No (without fixing)	Fix the body. Do not retry blindly.
`auth` (401)	Maybe (credential issue)	No	Re-prompt for a valid key
`auth` (403, scope)	Maybe	No	Request a key with `requiredScopes`
`not_found`	Maybe (“not found”)	No	Confirm id; confirm key ownership
`plan_limit`	Yes (paywall CTA)	No	Surface `upgrade.upgradeUrl` verbatim
`internal`	Yes (with `requestId`)	Once with backoff	Then escalate
`conflict` (in-flight idempotency)	No	Yes after 1s	Retry with same `Idempotency-Key`
`idempotency_conflict`	No	Yes with NEW key	Generate a fresh `Idempotency-Key`
`service_unavailable`	Yes (after retries)	Yes with backoff	Exponential backoff
`tos_not_accepted`	Yes (ToS link)	After user accepts	Surface `nextActions[0].url`

Stable code reference

Every code below is emitted by production code today. Agents may branch on code for finer-grained handling than type.

Auth (401 / 403)

`code`	HTTP	Source
`missing_authorization`	401	`src/api/middleware/apiKey.ts`
`invalid_authorization_format`	401	`src/api/middleware/apiKey.ts`
`key_not_found`	401	`src/api/middleware/apiKey.ts`
`key_revoked`	401	`src/api/middleware/apiKey.ts`
`insufficient_scope`	403	`src/api/middleware/scope.ts` — includes `requiredScopes`/`heldScopes`
`developer_context_unresolved`	401	Bootstrap / issue-key handlers when developer ctx is missing
`tenant_unresolved`	401	Catalog / verify handlers when owner ctx is missing
`developer_not_found`	404	`src/api/v1/me.get.ts` — dev account missing from Firebase Auth

Validation (400 / 410 / 413 / 422)

`code`	HTTP	Source
`invalid_request`	400	Zod validation failure (per-field)
`invalid_json`	400	Body parsing failure
`invalid_idempotency_key`	400	`src/api/middleware/idempotency.ts`
`invalid_storefront_id`	400	`src/api/services/translation/storefront-id.ts`
`invalid_product_id`	400	`src/api/services/translation/storefront-id.ts`
`invalid_email_syntax`	400	Bootstrap email validation
`invalid_email_mx`	400	Bootstrap MX-record check
`code_invalid`	400	`src/api/v1/users.verify.ts`
`code_expired`	410	`src/api/v1/users.verify.ts`
`idempotency_snapshot_unavailable`	410	`src/api/middleware/idempotency.ts` (oversize replay)
`payload_too_large`	413	Body parser
`no_products`	422	`src/api/v1/storefronts.publish.ts` (empty storefront)
`user_not_verified`	422	`src/api/v1/users.issueKey.ts` (pre-verify additional key)
`blocks_explicit_not_supported`	422	Storefront manifest (legacy block fields)
`theme_preset_not_supported`	422	Storefront manifest (theme presets not on plan)

Not found (404)

`code`	HTTP	Source
`storefront_not_found`	404	`src/api/v1/storefronts.*` — also fires on cross-tenant access
`user_not_found`	404	Verify, resend, issue-key handlers — also cross-tenant
`code_not_found`	404	`src/api/v1/users.verify.ts` — no active verification code

Conflicts (409)

`code`	HTTP	Source
`idempotency_in_flight`	409	`src/api/middleware/idempotency.ts` — emits `Retry-After: 1`
`idempotency_conflict`	409	`src/api/middleware/idempotency.ts` — different body, same key
`email_exists`	409	Bootstrap — email already registered

Plan / paywall (402)

`code`	HTTP	Source
`plan_blocks_publish`	402	`src/api/v1/storefronts.publish.ts` (`NO_ACTIVO` plan)
`plan_max_products_reached`	402	`src/services/catalog/productCreateCore.ts` — single-product POST would exceed the plan cap
`plan_max_storefronts_reached`	402	`src/services/catalog/createMenuCore.ts` — would exceed the per-plan storefront cap
`products_over_limit`	207/402	`src/api/v1/storefronts.create.ts` (manifest with too many products) — 207 partial OR 402 over cap

Rate limit (429)

`code`	HTTP	Source
`rate_limit_exceeded`	429	`src/api/middleware/rateLimit.ts` — `rpm_exceeded` / `rpd_exceeded`
`too_many_attempts`	429	`src/api/v1/users.verify.ts` — 3 wrong codes
`bootstrap_ip_rate_limited`	429	`src/api/services/bootstrap.service.ts`
`bootstrap_quota_exhausted`	429	`src/api/services/bootstrap.service.ts`
`resend_hour_limit`	429	`src/api/v1/users.resendVerification.ts`
`resend_day_limit`	429	`src/api/v1/users.resendVerification.ts`

ToS (451)

`code`	HTTP	Source
`tos_required`	451	Reserved on `storefronts.publish` — see ToS jurisdiction

Service / internal (500 / 503)

`code`	HTTP	Source
`api_disabled`	503	`src/api/middleware/featureFlag.ts` — kill switch
`verify_unexpected_state`	500	`src/api/v1/users.verify.ts` — defense-in-depth fall-through
`internal_error`	500	Unhandled exception path

What NOT to do

Do not branch on error.message — it’s localized via Accept-Language and may change. Branch on error.type (enum) and error.code (string).
Do not swallow nextActions[]. The most common agent-failure mode is silently retrying past a 402 (paywall) or 451 (ToS) without ever showing the user the action.
Do not auto-accept the ToS on the user’s behalf. The 451 → modal flow requires user input by design.
Do not retry invalid_request with the same body. Fix the body first.
Do not branch on HTTP status alone. Several types share a status (409 for two conflict shapes; 404 for both real-missing and cross-tenant). The type + code pair disambiguates.

Verification in code

src/api/contracts/error.zod.ts — the locked envelope schema (10 type values).
src/api/api-error.ts — the ApiError class that wires status + type + code + recovery hints.
src/api/middleware/errors.ts — the global error handler that emits the envelope.

Get Started

Concepts

Webhooks

Errors

Errors

Envelope shape

Field guarantees

The 10 error types

Recovery matrix

Stable code reference

Auth (401 / 403)

Validation (400 / 410 / 413 / 422)

Not found (404)

Conflicts (409)

Plan / paywall (402)

Rate limit (429)

ToS (451)

Service / internal (500 / 503)

What NOT to do

Verification in code

​Errors

​Envelope shape

​Field guarantees

​The 10 error types

​Recovery matrix

​Stable code reference

​Auth (401 / 403)

​Validation (400 / 410 / 413 / 422)

​Not found (404)

​Conflicts (409)

​Plan / paywall (402)

​Rate limit (429)

​ToS (451)

​Service / internal (500 / 503)

​What NOT to do

​Verification in code

Errors

Envelope shape

Field guarantees

The 10 error types

Recovery matrix

Stable code reference

Auth (401 / 403)

Validation (400 / 410 / 413 / 422)

Not found (404)

Conflicts (409)

Plan / paywall (402)

Rate limit (429)

ToS (451)

Service / internal (500 / 503)

What NOT to do

Verification in code