Common API error codes
Every API error returns an HTTP status and a JSON body with an error object holding a type, a code, a readable message, a param (often null) and a request_id. Use the code to find the fix below.
Should I retry?
| Status | Retry? |
|---|---|
400, 401, 403, 404, 405, 413 | No. Fix the request, key or account first |
402 | No. Wait for the window to reopen or add credit |
429, 503 | Yes, after Retry-After, with back-off |
500, 502, 504 | Yes, a few times with back-off |
400: something in the request
| Code | Fix |
|---|---|
invalid_json | The body isn’t valid JSON. Check quotes and commas |
messages_required | Include a non-empty messages list |
invalid_request | The request was rejected. Check the message format, tool definitions and parameters |
context_length_exceeded | Input plus max_tokens is over the model’s context window (see context_window in GET /v1/models). Shorten the conversation or lower max_tokens |
401 and 403: key, account or plan
See My API key isn’t working for each code, including invalid_api_key, revoked_api_key, public_key_rejected, origin_not_allowed, org_membership_required, account_disabled and plan_required. 403 model_not_in_plan means your plan doesn’t include the model you named.
404 and 405: model or endpoint
| Code | Fix |
|---|---|
model_not_found (404) | The model name isn’t served. Use an exact name from GET /v1/models. See Model not found |
endpoint_not_supported (405) | Only POST /v1/chat/completions (and GET /v1/models) are available |
402: plan or credit
quota_exhausted. See Fix a 402 error.
413: request too large
| Code | Limit |
|---|---|
payload_too_large | Body over about 2 MB |
too_many_messages | More than 500 messages |
429: too fast
rate_limited, model_busy, capacity_busy. See Fix a 429 error.
5xx: on Syntic’s side
| Code | Meaning |
|---|---|
internal_error (500) | Something went wrong at Syntic. Retry; quote the request_id if it persists |
upstream_error, upstream_unavailable, stream_error (502) | The model service failed or the stream broke. Retry |
authorization_unavailable, usage_check_unavailable, plan_check_unavailable (503) | A check couldn’t run, so the request wasn’t sent. Retry in a few seconds |
service_unavailable (503) | Temporary outage |
upstream_timeout (504) | The model took too long. Retry, or use streaming and a lower max_tokens |
If 5xx errors continue, check status.syntic.ai, then contact support with request IDs.
Full reference
Every code, with example bodies, is listed in the developer docs’ error code index.
Related
Was this page helpful?