Skip to content

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 ​

StatusCommon causeWhat to do
400Invalid parameters, malformed JSON, image size not allowedFix it according to the error message; do not retry
401Token invalid, deleted, expired, or missing (Invalid token)Check that the token is complete, has the Bearer prefix, and the header name is correct
403Insufficient balance or token quota; the token's group is no longer availableTop up or adjust the token quota; switch the token to an available group in the console
404The path does not exist; the upstream does not have this modelCheck the path and the model name
413The request body exceeds 256 MBCompress images or use file upload
429Too many requests or concurrency is fullWait and retry
500, 502Upstream errorRetry later
503No service is available right now; a wrong model name, or a model that is not in the token's group, also returns 503First check the model name and group in the model square; retry once they are correct
504Timed out waiting for the upstreamUse 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)