Jev API Errors: Codes, Causes and Fixes
Identify authentication, validation, rate-limit, overload, timeout, and connection failures before retrying.
On this page
Quick error tableSymptoms and verificationFix the class of failureSDK and provider differencesProduction recoveryQuick error table
| Symptom | Likely meaning | First action |
|---|---|---|
| 400 | Malformed JSON or provider rejection | Validate serialization and provider schema |
| 401 | Missing or invalid credentials | Check the key and Bearer header |
| 403 | Permission or provider policy | Verify account and endpoint access |
| 404 | Wrong URL or unavailable resource | Check the exact endpoint and model |
| 422 | Request validation failed | Inspect the field named in the response |
| 429 | Request or token limit exceeded | Honor retry-after; reduce concurrency |
| 529 | TypeSafe temporarily overloaded | Bounded backoff or review queue |
| Other 5xx | Transient upstream failure | Retry within a budget; keep a fallback |
| Timeout | Deadline exceeded | Record the timeout and retry cautiously |
| Connection error | DNS, network, or TLS failure | Check connectivity without exposing keys |
TypeSafe explicitly documents 401, 422, 429, and 529. The other entries are general HTTP/network diagnosis and may reflect a gateway rather than TypeSafe itself.
Symptoms and verification
Reproduce with the smallest valid request from the API guide. Capture HTTP status, request ID if supplied, actual endpoint, requested model, and elapsed time. Redact authorization headers and sensitive state. Do not paste a full production response into a public issue.
Fix the class of failure
Authentication errors need a valid key for the selected provider. Validation errors need corrected JSON. Rate limits need concurrency control or more time. A retry loop cannot repair the first two categories.
Use 401 checks, 422 checks, and 429 handling for step-by-step diagnosis. For a valid response with a weak decision, see low confidence instead of retrying identical text indefinitely.
SDK and provider differences
The official SDKs retry transient failures by default. Raw HTTP examples need their own bounded policy. A gateway may return a wrapper error with a different code; inspect its documentation and request identifiers separately. Do not replace an OpenRouter key with a direct key while keeping the gateway URL.
Production recovery
Define an application deadline, maximum attempts, and review fallback. Persist a job identifier before processing so retries cannot duplicate consequential actions. In the downloadable tutorials, evaluation failures print a review result and exit nonzero; they do not execute a downstream action.