← Back to API Dashboard
Troubleshooting

API Error Guide

Running into errors? This guide explains what each error means, when it happens, and exactly how to fix it.

CodeMeaningQuick Fix
400Invalid request formatCheck your request body
401Authentication failedCheck your API key
402Out of credits / budgetDeposit USDC or raise budget
429Too many requestsWait a few seconds, then retry
502Provider auth failedAuto-retried; contact support if repeated
503No providers availableRetry in a few seconds
504Provider timed outRetry your request
529Upstream overloadedWait 5–10s, then retry
01

Can't Connect

You'll see these when there's a problem with your API key or login session.

401Missing API key
You sent a request without an API key, or forgot the Authorization header.
✓
Add your key to the request header: Authorization: Bearer sk-ant-... (or use x-api-key header).
401Invalid API key
The API key you're using doesn't exist, was deleted, or has been disabled.
✓
Go to the API dashboard and check your keys. Generate a new one if needed — the old key may have been revoked.
401Invalid or expired token
You're using the web dashboard and your login session has expired (sessions last 24 hours).
✓
Log in again — your wallet and keys are all still there.
02

Out of Credits

You'll see these when your account or a specific key runs out of funds.

402Insufficient balance
Your USDC balance on DeRouter has been fully spent.
✓
Deposit more USDC on the API dashboard. Your balance updates instantly once the on-chain transaction confirms.
402API key budget ($N) exceeded
You set a spending cap on this key (e.g. $10/month) and it's been reached.
✓
Edit the key in Key Management to raise the budget, or generate a new key without a spending limit.
03

Too Many Requests

You'll see these when you're sending requests faster than your key's limits allow.

429Requests per minute limit (N) exceeded
You've sent more requests in the last minute than your key's RPM limit (default: 60/min).
✓
Wait a few seconds and retry. If you consistently need more throughput, contact support to raise your limit.
429Concurrent limit (N) exceeded
You have too many requests running at the same time (default limit: 5 concurrent).
✓
Wait for some requests to finish before sending new ones, or add a queue to your client code.
04

Invalid Request

You'll see these when there's something wrong with how the request is formatted.

400model is required
Your request body is missing the "model" field.
✓
Add a model to your request, e.g. "model": "claude-sonnet-4-6". Check the pricing table for all available models.
400Model "X" is not available
You requested a model that doesn't exist or isn't currently available.
✓
Check the error message for the list of supported models, or call GET /v1/models to see what's online right now.

Other request errors (prompt too long, invalid tool format, etc.) are passed through from the upstream API with the original message.

05

No Providers Available

These are temporary — DeRouter can't find a provider to handle your request right now, but one should become available shortly.

503No providers are currently online
No provider nodes are connected to the network for the model you requested.
✓
This usually resolves within 1–2 minutes as providers come online. Retry shortly.
503All providers are in scheduled rest
All providers for this model are in their scheduled rest period (16h online, 8h rest).
✓
Wait a few minutes — providers rotate on different schedules, so capacity returns quickly.
503All providers are at max concurrency
All providers are busy handling other requests and can't take yours right now.
✓
Retry in a few seconds. This usually clears up very quickly during normal load.
Tip: All "no provider" errors are transient. A simple retry with a short delay (2–5 seconds) will usually succeed.
06

Upstream Issues

These come from the AI provider (Anthropic or OpenAI) after DeRouter has already tried multiple providers automatically.

502Provider authentication failed
A provider's AI account credential has expired or been revoked.
✓
DeRouter automatically retries with a different provider. If you see this repeatedly, contact support — we'll look into it.
504Provider timed out
The AI provider didn't respond within 5 minutes (usually for very long responses).
✓
Retry your request. Consider breaking very long tasks into smaller chunks.
529Upstream API is temporarily overloaded
Anthropic or OpenAI's servers are under heavy load.
✓
Wait 5–10 seconds and retry. This is on the AI provider's side, not DeRouter.
07

Reading Error Responses

DeRouter returns errors in the same format as the AI provider you're calling, so your existing error handling code works without changes.

Claude API
/v1/messages
{ "type": "error", "error": { "type": "...", "message": "..." } }
OpenAI API
/v1/chat/completions, /v1/responses
{ "error": { "type": "...", "message": "..." } }
Need to contact support?

Every response includes a request-id header (e.g. req_a1b2c3...). Share this ID with us so we can trace exactly what happened with your request.

Still stuck? We're happy to help.

API DashboardContact Support