API· Last updated 2026-09-21

Jev API error envelope

TypeSafe documents standard HTTP statuses plus a JSON body that explains the failure. Official SDKs map those to typed exceptions. This unofficial page is the envelope + tree. Canonical table: docs.typesafe.ai/api. We do not sell keys.

Documented first-party statuses

Status	Meaning (TypeSafe API reference)	Retry?
`401 Unauthorized`	Missing or invalid API key	No — fix `Authorization`
`422 Unprocessable Entity`	Body failed validation; body names the field	No — fix the body
`429 Too Many Requests`	Token/s or request/min limit	Yes — exponential backoff; honor `retry-after`
`529 Overloaded`	TypeSafe temporarily overloaded	Yes — same backoff

Official client SDKs retry 429/529 by default. Raw HTTP must implement it.

We will not invent extra first-party codes. If you see one, capture the JSON and ask TypeSafe.

Symptom → fix (one tree)

Have answers?
  ├─ yes → application failure (confidence, policy). Not this envelope.
  └─ no
       ├─ 401 → /error/jev-error-unauthorized
       ├─ 422 → /error/jev-error-invalid-input or schema-mismatch
       ├─ 429 / 529 → sleep, retry; prefer official SDK
       ├─ 402 → OpenRouter (or similar) credits — callout
       ├─ customer_verification / 403 must-supply-key → Vercel/marketplace — callout
       └─ timeout / connection → network; SDK APIConnectionError / APITimeoutError

Log: status, body, request id if the door sends one, and which host you called. A 401 on Gateway is not a 401 on api.typesafe.ai.

Channel callouts (not separate URL trees)

Rivals often give each status its own page. We keep them here:

402 insufficient credits — typical OpenRouter wallet. Top up on OpenRouter. TypeSafe’s public error table does not list 402.
403 must supply an API key — missing marketplace key or Worker binding.
Vercel customer verification required — their account gate; verify on Vercel.
529 — first-party overload. Marketplace may remap it; still back off.
Max tokens / context — shrink state; first-party budgets are on the models page.

What a success envelope is not

A success body has model, answers, and usage — see response shape. Do not look for answers on 4xx/5xx.

FAQ

Should I retry 422 after a deploy? Only after you change the body. Retrying the same invalid JSON wastes quota.

Does usage appear on errors? Do not assume it. Meter from successful calls and the door’s invoice.

Hub: API. Siblings: unauthorized, invalid input.

Sources

Public TypeSafe or adjacent documentation only. No private claims.