← Back to Docs
Troubleshooting
API Error Guide
What each API error means, when it happens, and how to fix it. Card messages are the English error.message the API actually returns — match on that string or on error.type.
| Code | Meaning | Quick Fix |
|---|---|---|
| 400 | Invalid request | Fix the request body — do not retry as-is |
| 401 | Authentication failed | Check your API key |
| 402 | Out of credits / budget | Deposit USDC or raise the key budget |
| 403 | Rejected by platform policy | Do not retry — contact support if this is a mistake |
| 413 | Request body too large | Shrink the prompt or split attachments |
| 429 | Rate limited | Wait Retry-After, then retry |
| 500 | Internal error | Retry shortly |
| 502 | Provider auth failed (remapped) | Already retried internally; contact support if it repeats |
| 503 | No providers available | Retry in a few seconds |
| 504 | Provider timed out | Retry your request |
| 529 | Anthropic overloaded (upstream) | Wait 5–10s; check status.anthropic.com |
01
Can't Connect
Your DeRouter API key (or dashboard login) is missing or invalid. This is about YOUR credential — not a provider node.
401authentication_error
Missing API key
The request had no API key (no Authorization: Bearer and no x-api-key).
✓
Send Authorization: Bearer sk-ant-... (or x-api-key). Create a key on the API dashboard if you don't have one.
401authentication_error
Invalid API key
The key does not exist, was deleted, or has been disabled.
✓
Open the API dashboard, check the key, and generate a new one if it was revoked.
401authentication_error
Invalid or expired token
Dashboard only: your login session expired (JWT, 24h). This is not returned by /v1/messages.
✓
Log in again — wallet and keys are unchanged.
02
Out of Credits
402 only fires when remaining budget or wallet balance cannot cover even one worst-case request of this model. Occupied slots with remaining headroom return 429 instead.
402billing_error
Insufficient balance. Top up the wallet.
Wallet USDC cannot cover one request of this model (wallet-balance cap = 0).
✓
Deposit USDC on the API dashboard. Balance updates as soon as the on-chain tx confirms.
402budget_exceeded
API key budget headroom is below the worst-case cost of one {model} request. Use a cheaper model or raise the key budget.
This key's remaining budget cannot cover one request of this model (key-budget cap = 0).
✓
Raise the key budget in Key Management, switch to a cheaper model, or use a key without a cap.
If slots are merely busy (cap > 0), you get 429 with retry-after — not 402. Do not treat every money-related failure as “out of funds”.
03
Too Many Requests
Per-key, per-family, or platform-wide RPM / concurrency. Body includes scope, reason, retry_after_sec; headers Retry-After and x-ratelimit-scope.
429rate_limit_error
API key limit reached for {model}: {N} requests per {window}. Retry in ~{sec}s or contact admin for a higher quota.
This key hit its RPM window for this model (or the model family).
✓
Wait retry_after_sec (1m=60s, 5m=300s, 30m=1800s, 1h=3600s). Contact support for a higher quota.
429rate_limit_error
API key concurrent request limit reached for {model} ({N} in-flight). Retry shortly.
Too many in-flight requests on this key for the model (or family).
✓
Wait for in-flight calls to finish, or queue on the client. Concurrent retry-after is 5s.
429rate_limit_error
Platform is over capacity for {Family} models. This is not specific to your API key. Retry in ~{sec}s.
Platform-wide RPM for that model family is full. The numeric cap is omitted on purpose.
✓
Retry after ~retry_after_sec. This is not your key's quota.
429rate_limit_error
Platform is over concurrent capacity for {Family} models. This is not specific to your API key. Retry shortly.
Platform-wide concurrency for that family is full.
✓
Retry shortly. Same as above — not your key.
If the message says “0 requests per …”, the key is blocked for that model (circuit breaker or admin) — waiting will not help; contact support. Upstream 429s are rewritten to: Rate limit exceeded. Please retry after a brief wait.
04
Invalid Request
The request itself is wrong. Changing providers will not help — fix the body.
400invalid_request_error
model is required
Body is missing the model field.
✓
Set model, e.g. "model": "claude-sonnet-4-6". GET /v1/models lists what is live.
400invalid_request_error
model: {name} is not a valid model ID. See /providers/models for available models.
model is not a known id.
✓
Use an id from the error message or GET /v1/models.
400invalid_request_error
1M context ([1m]) is not available for {model}; remove [1m] for standard 200K context.
You appended [1m] on a model that does not serve the 1M context window.
✓
Drop [1m] for the standard window, or pick a 1M-capable model.
400invalid_request_error
This request was rejected because the conversation exceeds the context window included with {model}; beyond it Anthropic requires additional usage credits. Options: switch to claude-sonnet-5 (supports 1M context) or claude-opus-4-8[1m], or run /compact to reduce the conversation below the included window.
Conversation is past the included context window. Anthropic would demand extra usage credits; we return 400 so clients stop retrying a 429.
✓
Switch to claude-sonnet-5 (1M) or claude-opus-4-8[1m], or /compact the thread.
400invalid_request_error
Requests from the {Framework} framework are not supported. We do not accept requests from third-party agent frameworks, as the underlying Claude subscriptions are subject to Anthropic's usage policy. Direct API usage, Claude Code CLI, and Codex CLI are supported.
The request looks like a third-party agent framework (OpenCode, OhMyOpenCode, OpenClaw, Hermes Agent) or the same pattern was already flagged by Anthropic.
✓
Use Claude Code CLI, Codex CLI, or a direct API client. Dynamic blocks expire in up to 1 hour.
413invalid_request_error
Request body exceeds {N} MB. Reduce prompt size (or split image/PDF attachments) and retry.
JSON body exceeded the size cap (32 MB on /v1/messages, 100 MB on OpenAI / images).
✓
Shrink the prompt or split image/PDF attachments.
Other invalid_request_error messages (prompt too long, bad tool_use, …) are passed through from upstream with ids/IPs stripped. Sampling-parameter rejections (temperature / top_p / top_k) only apply when that key has reject_sampling_params enabled.
05
Rejected by Platform Policy
Terminal 403. Failover will not change the outcome. Do not retry the same request.
403content_refusal
This request was declined by platform policy and will not be processed. If you believe this is an error, contact support.
A content-matching refusal rule hit this request (error.type = content_refusal).
✓
Do not retry. If you believe this is a mistake, contact support with the request-id.
403pool_no_capacity
This request was rejected: the traffic pattern matches prohibited extraction of model outputs (distillation). If you believe this is an error, contact support.
This traffic was classified as prohibited extraction of model outputs, or the assigned pool has no capacity and is configured to reject (error.type = pool_no_capacity).
✓
Do not retry. Contact support with the request-id if this is unexpected.
Operators may attach a custom message; you might not see the default sentence. 403 here is NOT an expired provider credential — those are remapped to 502.
06
No Providers Available
Temporary — DeRouter has no healthy node for this model right now. 503 uses api_error (not overloaded_error) so SDKs do not treat it as Anthropic 529.
503api_error
No providers are currently online for the requested model.
No provider is online for this model.
✓
Usually clears in 1–2 minutes. Retry with a short delay.
503api_error
All providers for this model are in scheduled rest. Please retry in a few minutes.
All providers for this model are in scheduled rest.
✓
Wait a few minutes — rest windows are staggered.
503api_error
All providers for this model are at max concurrency. Please retry shortly.
All providers are at max concurrency.
✓
Retry in a few seconds.
503api_error
All providers for this model are temporarily rate-limited by upstream. Please retry in a few minutes.
All providers are in upstream rate-limit cooldown.
✓
Retry in a few minutes.
503api_error
All providers for this model have exhausted their budget. Please retry after the next reset.
All providers have exhausted their budget until the next reset.
✓
Retry after the next quota reset, or try another model.
Any 503 api_error from this layer is transient (busy, rest, cooldown, reconciling, …). Retry with 2–5s backoff. Do not confuse with 403 (terminal) or 529 (Anthropic overload).
07
Upstream Issues
The AI vendor failed after DeRouter already failed over across providers. Raw upstream bodies are not forwarded (except actionable 400s).
502authentication_error
Provider authentication failed. The system will automatically retry with another provider.
A provider's vendor credential expired or was revoked. Upstream 401/403 are remapped to 502 so you do not think YOUR key is dead.
✓
DeRouter already retried other nodes. If this repeats, contact support with the request-id.
504api_error
Provider timed out
The provider did not respond within 5 minutes (usually huge completions).
✓
Retry. Split very long jobs.
529overloaded_error
Anthropic's servers are temporarily overloaded (HTTP 529). This error originates from Anthropic and affects all Claude API users — it is not caused by your key or balance. Retry in a few seconds; if it persists, check status.anthropic.com.
Anthropic returned HTTP 529. This hits every Claude API user, not your key or balance.
✓
Wait 5–10s. If it persists, check status.anthropic.com.
500api_error
Internal server error
Gateway caught an unexpected exception.
✓
Retry once. If it repeats, send the request-id to support.
502api_error
Upstream service is temporarily unavailable. Please try again later.
Upstream 500/502/504 after failover, or OpenAI did not return a completed response object.
✓
Retry shortly.
08
Reading Error Responses
Envelope matches the vendor you called, so existing SDK error handling still works. Switch on error.type + HTTP status together — the same type can appear on more than one code.
Claude API
/v1/messages
{
"type": "error",
"error": {
"type": "...",
"message": "..."
}
}
OpenAI API
/v1/chat/completions, /v1/responses, /v1/images/*
{
"error": {
"type": "...",
"message": "..."
}
}
error.type Reference
error.type is the category. Combine it with the HTTP status before deciding to retry.
| error.type | HTTP Code | Meaning | Action |
|---|---|---|---|
| authentication_error | 401 | Your DeRouter API key is missing or invalid | Fix the key — do not retry |
| authentication_error | 502 | A provider node's vendor login failed (not your key) | Retry; contact support if repeated |
| billing_error | 402 | Wallet balance cannot cover one request | Deposit USDC |
| budget_exceeded | 402 | This key's budget cannot cover one request | Raise the key budget or use a cheaper model |
| invalid_request_error | 400 / 413 | Bad request (missing model, too large, long-context, third-party, …) | Fix the body — do not retry as-is |
| not_found_error | 404 | GET /v1/models/:id — model unknown or inactive | Pick a live model id |
| rate_limit_error | 429 | RPM / concurrency (yours or platform) or sanitized upstream 429 | Honor retry_after_sec; if limit is 0, contact support |
| content_refusal | 403 | Content matched a refusal rule | Do not retry — contact support |
| pool_no_capacity | 403 | Pool has no capacity / traffic classified as prohibited extraction | Do not retry — contact support |
| api_error | 503 | DeRouter has no available provider | Retry in 2–5 seconds |
| api_error | 500/502/504 | Gateway or upstream server error | Retry shortly |
| overloaded_error | 529 | Anthropic overloaded (HTTP 529) | Wait 5–10 seconds; check status.anthropic.com |
403 content_refusal / pool_no_capacity = terminal, do not retry. 503 api_error = our nodes, retry. 529 overloaded_error = Anthropic, retry later. 502 authentication_error = provider credential, not your key.
Need to contact support?
Every response includes a request-id header (e.g. req_a1b2c3...). Share this ID so we can trace the exact request.
Still stuck? We're happy to help.