Errors & troubleshooting
Interpret error codes and find the right next step.
Read a gateway error
{
"error": {
"code": 400,
"type": "invalid_request",
"message": "Unknown request field: temperture",
"metadata": {
"retryable": false
}
},
"id": "gen-example"
}Chat gateway errors identify their type, HTTP status, retryability, and request ID. Provider-specific errors can also identify the upstream provider. Other account endpoints may return an HTTP detail field instead of the chat error envelope.
Error codes
| Type | HTTP | Next step | Meaning |
|---|---|---|---|
| invalid_request | 400 | Fix the request | Unknown fields, invalid options, or malformed messages. |
| context_length_exceeded | 400 | Reduce the context | The request does not fit the endpoint. CyberRouter does not silently truncate it. |
| authentication_error | 401 | Check your key | The CyberRouter credential is missing, invalid, expired, or revoked. |
| payment_required | 402 | Check credits and limits | Available credits or an account/key spending allowance is exhausted. |
| permission_error | 403 | Check access | The requested operation is not allowed for this credential. |
| not_found | 404 | Check the identifier | The model, endpoint, or accessible generation was not found. |
| rate_limit_exceeded | 429 | Retry with backoff | An account concurrency limit, gateway rate limit, or upstream provider limit was reached. |
| provider_error | 502 | Retry with backoff | An upstream service failed. |
| no_endpoints | 503 | Check connections and filters | No eligible endpoint can serve this request. |
| timeout | 504 | Retry with backoff | The upstream request timed out. |
| internal_error | 500 | Keep the request ID | An unexpected gateway error needs investigation. |
Concurrent requests
Each account can run up to three inference requests at a time, shared across its API keys, browser sessions, models, and providers. A streaming request counts until delivery and cleanup finish. Up to six more requests per account can wait for a slot.
The gateway runs up to eight requests across accounts and queues up to 24 more. Admission, including authentication and waiting, has a 30-second deadline. Waiting requests do not start model calls or consume credits. The X-CyberRouter-Queue-Ms response header reports time waiting for an inference slot; X-CyberRouter-Admission-Ms also includes authentication.
A full account queue returns HTTP 429 with error.metadata.reason set to account_queue_full. A full gateway queue or expired wait returns HTTP 503 with gateway_queue_full or gateway_queue_timeout. Honor Retry-After and retry with backoff. Other request and input limits also apply.
Find the right fix
- For 401, confirm you sent a CyberRouter key, not a provider key.
- For 402, inspect available credits, holds, and key limits. Check the provider account’s own billing if its response reports a payment problem.
- For no_endpoints, verify the connected provider, model access, and routing filters.
- For a JSON parsing error, inspect the response status and content type. HTML often means a frontend or proxy error page reached your API client.
- For a retryable failure, use bounded retries with backoff. Keep the request ID and check its Usage entry before repeating work that may already have been billed.