Troubleshooting

When a request fails, check the error code first, then confirm the related Dashboard state.

Quick diagnosis

Symptom	Check first
`invalid_api_key`	Header, copied key, key state, key expiry.
404 `model_not_found`	Model ID spelling and key model scope.
`insufficient_quota`	Billing balance and key budget.
400 `invalid_request`	JSON body, `messages`, `max_tokens`, `temperature`, `top_p`.
413 `request_too_large`	Input size. Retrying the same payload will not work.
429 `rate_limit_exceeded`	Request rate and `retry-after`.
429 `token_rate_limit_exceeded`	Token volume and `retry-after`.
504 `upstream_request_timeout`	Client timeout, model speed, provider health.
`upstream_unavailable`	Provider/channel availability or alternate model.
`upstream_error` or `gateway_error`	Status page, provider issue, alternate model.
Playground succeeds but local code fails	Local base URL, environment variables, proxy, firewall.

`invalid_api_key`

The header must be:

Authorization: Bearer YOUR_NEXOROUTER_API_KEY

Common causes:

Missing Bearer.
No space after Bearer.
Using a key from OpenAI, Anthropic, or another provider.
Disabled key.
Expired key.
Incomplete copy.
Environment variable not loaded by the current shell, dev server, or deployment.

`model_not_found`

Use Models or GET /v1/models as the source of truth.

curl https://api.nexorouter.com/v1/models \
  -H "Authorization: Bearer $NEXOROUTER_API_KEY"

If the model is listed but the request still fails, check whether the API key has a restrictive model scope.

`insufficient_quota`

Open Billing and API Keys:

Check workspace balance.
Check the key budget.
Check Usage Logs for recent spend.
Add balance or create a new key with the right budget.

Request too large

request_too_large is permanent for that exact payload. Reduce the input, split the task, summarize earlier context, or choose a model path designed for larger context once it is available in the public catalog.

Rate limits

rate_limit_exceeded and token_rate_limit_exceeded include rate-limit headers and retry-after. Wait for the window or reduce concurrency.

Do not implement tight retry loops. Rate-limited requests are rejected before they reach the provider, so retrying immediately usually just repeats the 429 until the window resets.

Timeouts

Recommended client timeouts:

Model type	Starting timeout
Standard chat	`60` seconds
Slow reasoning-style model	up to `180` seconds

If your client cancels early and immediately retries, each retry is a new request.

What to send support

Send:

account email;
request time;
request ID;
model ID;
error code;
API key name or last four characters.

Do not send:

full API key;
password;
payment card data;
private keys;
full source code unless requested through a private support channel.