API · Last updated 2026-09-21

Jev API error envelope

TypeSafe documents standard HTTP statuses plus a JSON body that explains the failure on POST /v1/systemone and GET /v1/models. Official SDKs (typesafe-sdk on Python ≥ 3.10, @typesafe-ai/sdk on Node 20+) map those to typed exceptions. This unofficial page is the envelope + tree. Canonical table: docs.typesafe.ai/api.

This page is for builders wiring TypeSafe Jev (System One) into agents, routing, or evals. jev.pro is an independent unofficial field guide — not affiliated with TypeSafe AI. We do not sell or issue keys.

Documented first-party statuses

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.

A success body has model, answers, and usage. Do not look for answers on 4xx/5xx. Application failures (low confidence, policy block) are often 200 with a distribution you refuse — not this envelope.

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 vendor claims on the models page (64k state+all questions; 32k state+longest question).

Production notes

Vendor-claimed 1200 RPM is a ceiling, not a reason to tight-loop. Retries may re-spend input tokens (vendor claim: $0.042 / million input, output free). Side effects need your idempotency store. Pin jev-1.13.0 so an alias move is not misread as a new error class. Schema-safe requests can still 200 with a wrong-in-the-world label.

See also

• API hub — HTTP contract cluster
• Errors and retries — retry table without channel callouts
• Unauthorized — 401 symptom page
• Invalid input — 422 symptom page

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.

Is the error JSON the same as the success envelope?

No. Success is model / answers / usage. Errors are status + a field-describing body.

Can I invent a 418 for “model unsure”?

No. Uncertainty is a 200 with a flat distribution or a mid Noul.

What this page does not claim

• Official TypeSafe status, logos, or support.
• That jev.pro sells, issues, or proxies API keys.
• Extra first-party HTTP routes beyond POST /v1/systemone and GET /v1/models unless the API reference lists them.
• Invented latency SLOs, search volume, or unofficial prices.
• That a schema-constrained answer is automatically factually correct.

Disclaimer

This is an independent unofficial site and is not affiliated with TypeSafe AI; official documentation is available at https://docs.typesafe.ai. Never treat jev.pro as TypeSafe official documentation. We do not sell, issue, or proxy API keys.