Errors
Every error the Nexrouting API returns: HTTP status, code, what it means and what to do, plus the error shapes and when to retry.
Errors come back as JSON with an HTTP status. All endpoints except /v1/messages use the OpenAI shape:
{ "error": { "message": "Insufficient credits. Add credits in your Nexrouting dashboard and try again.", "type": "insufficient_credits", "param": null, "code": "insufficient_credits" }}/v1/messages uses the Anthropic shape, which has no code. Use the HTTP status and error.type there:
{ "type": "error", "error": { "type": "billing_error", "message": "Insufficient credits. Add credits in your Nexrouting dashboard and try again." }}Every response, errors included, has an x-request-id header; the only exception is a 405 for a wrong HTTP method. Send the ID to support when you report a problem.
Error codes
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_json | The body is not valid JSON. | Fix the body. |
| 400 | invalid_body | The body is JSON, but not an object. | Send a JSON object. |
| 400 | missing_model | There is no model in the body. | Add a model ID. |
| 400 | unsupported_endpoint | The model doesn't support this endpoint. The message lists the endpoints it does support. | Use one of those, or another model. |
| 400, 422 | invalid_request | The model provider rejected the request, for example a parameter the model doesn't accept. The message says why; param names the field when known. | Change the request. Sending it again unchanged fails again. |
| 401 | missing_api_key | No key in Authorization or x-api-key. | Send Authorization: Bearer <key>. |
| 401 | invalid_api_key | The key is unknown or revoked. | Check the key, or create a new one. |
| 401 | api_key_expired | The key is past its expiry date. | Create a new key, or change the date. |
| 402 | insufficient_credits | Your balance is zero or below, or too low for this prompt. | Add credits. |
| 402 | key_budget_exceeded | The key has spent its budget. | Raise the budget, or use another key. |
| 403 | account_suspended | Your organization is suspended. | Contact support. |
| 403 | model_not_allowed | The key may not use this model. | Add the model to the key, or use another key. |
| 404 | model_not_found | The model doesn't exist or is not available right now. The message suggests alternatives. | Check GET /v1/models. |
| 404 | not_found | Unknown endpoint. | Check the path. |
| 405 | – | Wrong HTTP method for this endpoint, such as GET on /v1/chat/completions. This response has an empty body and no x-request-id. | Use the method from the API reference. |
| 413 | request_too_large | The body is larger than 32 MB, or the model rejected the request as too large. | Send less, or split the request. |
| 429 | rate_limit_exceeded | Too many requests per minute for this key, or the model is busy on every route. | Wait the number of seconds in retry-after, then retry. |
| 500 | internal_error | Something went wrong on our side. | Retry with backoff. If it keeps happening, contact support with the request ID. |
| 503 | model_unavailable | No route for this model could answer. | Retry after a short wait, or use another model or lane. |
| 200 (in a stream) | stream_interrupted | The connection to the model was lost during a stream. | Retry the request. |
In Usage you may also see status 499: the connection was closed before the answer was complete.
Error types
The type follows the HTTP status:
| Status | OpenAI error.type | Anthropic error.type |
|---|---|---|
| 400 | invalid_request_error | invalid_request_error |
| 401 | authentication_error | authentication_error |
| 402 | insufficient_credits | billing_error |
| 403 | permission_error | permission_error |
| 404 | invalid_request_error | not_found_error |
| 413 | invalid_request_error | request_too_large |
| 422 | invalid_request_error | invalid_request_error |
| 429 | rate_limit_error | rate_limit_error |
| 500 | server_error | api_error |
| 503 | server_error | overloaded_error |
When to retry
Retry 429, 500, 503 and an interrupted stream, with exponential backoff (for example 1, 2 and 4 seconds), and honour retry-after when it is there. The OpenAI and Anthropic SDKs already retry 429 and 5xx responses a couple of times.
Don't retry 400, 401, 402, 403, 404 or 413 without changing something: the same request fails the same way. Before it returns 503, the gateway has already tried every route it has for the model, so wait a moment before you retry.
import openai try: reply = client.chat.completions.create( model="openai/gpt-6-astra", messages=[{"role": "user", "content": "Hello"}], )except openai.RateLimitError as e: print("Slow down, retry after", e.response.headers.get("retry-after"), "s")except openai.APIStatusError as e: print(e.status_code, e.response.headers.get("x-request-id"), e.message)