Error Handling

When an API request fails, NexusModels returns an HTTP status code and an error response.

Example Error Response

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Common HTTP Status Codes

HTTP Status	Description
200	Request completed successfully
400	Invalid request parameters
401	Missing or invalid API key
403	Access to the requested model or endpoint is denied
404	Endpoint or model not found
429	Rate limit or budget exceeded
500	Internal server error
502	Upstream model provider error
503	Service temporarily unavailable

Budget Exceeded

When a virtual key, user, or team exceeds its budget, the API may return:

HTTP/1.1 429 Too Many Requests

The client should stop retrying and check the available budget or remaining quota.

Retry Recommendations

For 429, 500, 502, and 503 responses, use a limited exponential backoff strategy:

First retry: wait 1 second
Second retry: wait 2 seconds
Third retry: wait 4 seconds

Do not retry authentication errors, model permission errors, or exhausted budgets indefinitely.