Troubleshooting

API Error Guide

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

Code	Meaning	Quick Fix
400	Invalid request format	Check your request body
401	Authentication failed	Check your API key
402	Out of credits / budget	Deposit USDC or raise budget
429	Too many requests	Wait a few seconds, then retry
502	Provider auth failed	Auto-retried; contact support if repeated
503	No providers available	Retry in a few seconds
504	Provider timed out	Retry your request
529	Upstream overloaded	Wait 5–10s, then retry

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).

✓

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.

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 this model's RPM limit (default: Claude 30/min, GPT 200/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 on this model (default: Claude 2 concurrent, GPT 10 concurrent).

✓

Wait for some requests to finish before sending new ones, or add a queue to your client code.

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.

No Providers Available

These are temporary — DeRouter can't find a provider to handle your request right now, but one should become available shortly. Note: 503 means DeRouter providers are temporarily unavailable, which is different from 529 (AI provider overloaded).

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.

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.

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": "..." } }

error.type Reference

The error.type field in the response body tells you the error category, helping you determine the cause and how to handle it:

error.type	HTTP Code	Meaning	Action
authentication_error	401	Authentication failed — invalid API key or token	Check your API key
billing_error	402	Insufficient balance or key budget exceeded	Deposit or raise budget
invalid_request_error	400	Bad request (missing model, invalid format, etc.)	Check request body
rate_limit_error	429	RPM or concurrency limit exceeded	Wait a few seconds, retry
api_error	503	DeRouter has no available providers	Retry in 2–5 seconds
api_error	500/502/504	Upstream server error (500/502/504)	Retry shortly
overloaded_error	529	AI provider (Anthropic/OpenAI) is overloaded	Wait 5–10 seconds, retry

Key distinction: 503 (api_error) = DeRouter provider issue, 529 (overloaded_error) = AI provider overload. Different causes, different handling.

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 Dashboard Contact Support