Errors and retries
Error format
The error body follows the protocol you call: OpenAI endpoints return the OpenAI format, Claude endpoints the Claude format, and Gemini endpoints the Gemini format, so the error handling of the official SDKs works as is.
OpenAI format:
json
{
"error": {
"message": "Invalid token (request id: 2026111605183113110223...)",
"type": "new_api_error",
"code": ""
}
}Claude format:
json
{"type": "error", "error": {"type": "...", "message": "..."}}Gemini format:
json
{"error": {"code": 503, "message": "The service is temporarily unavailable. Try again later.", "status": "UNAVAILABLE"}}The request id in the error message is used for troubleshooting. Include it when you contact support.
Common status codes
| Status | Common cause | What to do |
|---|---|---|
| 400 | Invalid parameters, malformed JSON, image size not allowed | Fix it according to the error message; do not retry |
| 401 | Token invalid, deleted, expired, or missing (Invalid token) | Check that the token is complete, has the Bearer prefix, and the header name is correct |
| 403 | Insufficient balance or token quota; the token's group is no longer available | Top up or adjust the token quota; switch the token to an available group in the console |
| 404 | The path does not exist; the upstream does not have this model | Check the path and the model name |
| 413 | The request body exceeds 256 MB | Compress images or use file upload |
| 429 | Too many requests or concurrency is full | Wait and retry |
| 500, 502 | Upstream error | Retry later |
| 503 | No service is available right now; a wrong model name, or a model that is not in the token's group, also returns 503 | First check the model name and group in the model square; retry once they are correct |
| 504 | Timed out waiting for the upstream | Use streaming, or split the task into smaller ones and retry |
Got a web page back?
A 200 response whose content is HTML means the path is missing /v1 and the request landed on the website home page. The OpenAI SDK Base URL must be https://api.codingrouter.ai/v1.
Retry advice
- Do not retry 400, 401, 403, 404 or 413; the result will not change.
- 429 and 5xx can be retried with exponential backoff: wait 1 second, 2 seconds, 4 seconds, and so on, for at most 3 to 5 retries.
- If 503 keeps appearing, rule out the model name and group first.
- For long-running requests (long text, reasoning models, images), set the client timeout to 300 seconds or more, or use streaming.
Still not working?
Send the following to support:
- Request time (to the minute)
- Model name and API path
- The full error message (including the
request id) - The token name (do not send the token itself)
