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.
De documentatie is in het Engels.
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)