Jev API Errors: Every Error Code and Fix
Last checked · Independent guide, not affiliated with TypeSafe AI
Most Jev errors come from four causes: a missing or wrong key (401, 403), a malformed request or wrong model name (400, 422), a state that is too long (400 max_tokens_exceeded), or capacity limits (429, 529). Vercel and OpenRouter add account errors of their own: customer_verification_required and 402 Insufficient credits.
We reproduced every TypeSafe error below with real calls to api.typesafe.ai on September 19, 2026, except 429 and 529, which come from TypeSafe’s documentation and our runs on Vercel. The exact wording matters when you search logs, so it is quoted as the API returned it.
TypeSafe API errors
Section titled “TypeSafe API errors”| HTTP | What the body says | Usual cause | Page |
|---|---|---|---|
| 401 | authentication_error: “Cannot authenticate with the server. Please check your API key and try again.” |
Wrong, mistyped or revoked key | 401 |
| 403 | authentication_error: “Must supply an API key! Check your request and try again.” |
No Authorization header at all |
403 |
| 400 | api_usage_error: “Invalid request.” |
Unknown question type, such as Vercel’s boolean |
400 |
| 400 | api_usage_error: “Unknown model: jev-1.13” |
Model name not recognized | 400 |
| 400 | {"error_type": "max_tokens_exceeded"} with no message |
State plus question over about 32k tokens | max_tokens_exceeded |
| 422 | A list of fields, each with “Field required” | Missing model, questions or a Choice’s criteria |
422 |
| 429 | Too Many Requests | Over your rate limit | 429 |
| 529 | Overloaded | TypeSafe is out of capacity for the moment | 529 |
TypeSafe’s documentation lists only 401, 422, 429 and 529. In practice, a missing key returns 403 and several validation problems return 400, so handle those codes too.
Platform errors
Section titled “Platform errors”| Where | Error | Cause | Page |
|---|---|---|---|
| Vercel AI Gateway | customer_verification_required |
No card on the Vercel team | Vercel verification |
| Vercel AI Gateway | Rate limit error on the free tier | Per-model free-tier throttle | 429 |
| OpenRouter | 402 “Insufficient credits. Add more using https://openrouter.ai/credits” | Empty OpenRouter balance | 402 |
| OpenRouter | 401 “No cookie auth credentials found” | Request sent without an Authorization header |
OpenRouter page |
What the official SDKs do with errors
Section titled “What the official SDKs do with errors”Both official SDKs turn HTTP errors into typed exceptions and retry the temporary ones for you:
| Status | Python (typesafe-sdk) |
JavaScript (@typesafe-ai/sdk) |
Retried by default? |
|---|---|---|---|
| No key configured | TypeSafeError (“No API key was provided…”) raised before any request |
TypeSafeError, same message |
No |
| 400 | TypeSafeBadRequestError |
BadRequestError |
No |
| 401 | TypeSafeAuthenticationError |
AuthenticationError |
No |
| 403 | TypeSafePermissionDeniedError |
PermissionDeniedError |
No |
| 422 | TypeSafeUnprocessableEntityError |
UnprocessableEntityError |
No |
| 408, 429, 500-599 (includes 529) | TypeSafeRateLimitError for 429; TypeSafeInternalServerError for 5xx |
RateLimitError; InternalServerError |
Yes: 2 retries with backoff from 0.5 s up to 5 s, honoring Retry-After |
Python error messages have the form POST https://api.typesafe.ai/v1/systemone: 401 <message> (request_id=req_...). Keep the request_id if you need to contact TypeSafe about a failed call.
A quick triage order
Section titled “A quick triage order”- Any 4xx is your request. Do not retry it unchanged. Check the key, the model name, the question types and the size of the state.
- 429 and 529 are capacity. Retry with exponential backoff; the SDKs already do. If they persist, check Is Jev down? and your rate limits.
- Platform errors are account settings. A card on Vercel, credits on OpenRouter. No code change will fix them.