API Reference

Error Handling

Errors follow the same { error: { message, type, code } } shape as the OpenAI API, so existing error-handling code carries over unchanged.

Error shape

Every non-2xx response body has a single error object:

429 Too Many Requests

{
  "error": {
    "message": "Rate limit reached for aniron/llama-3.1-70b. Retry after 2 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Status codes

Status	error.type	Meaning
400	invalid_request_error	Malformed request — a missing required field, invalid parameter value, or bad JSON.
401	authentication_error	Missing, malformed, or revoked API key.
403	permission_error	The key is valid but not permitted to use this model or endpoint.
404	not_found_error	Unknown model ID or endpoint.
429	rate_limit_error	Per-key rate limit exceeded, or account credit balance depleted.
500	api_error	Unexpected error on Aniron’s side.
503	service_unavailable_error	The upstream model provider is temporarily unavailable.

Rate limits and fallbacks

A 429 from the primary model is exactly the condition fallbacks exist for: if you set a fallbacks array, Aniron retries the same request against the next model automatically and you never see the error. A 429 only reaches your client when every model in the chain (or the single model, if no fallbacks are set) is rate-limited, or when the account's prepaid credit balance is depleted — see Managing Credits. A response includes a Retry-After header (seconds) when the limit is time-based.

Retry guidance

Retry 429 and 503 with exponential backoff and jitter; respect Retry-After when present.
Do not retry 400, 401, 403, or 404 — the request is invalid regardless of attempt count.
Retry 500 once or twice with backoff; if it persists, treat it as an incident and check the dashboard.
Prefer configuring a fallbacks array over client-side retries for rate limits — it's faster and avoids a wasted round trip.

Related resources

Docs

Reduce 429s in production

Add a fallbacks array so rate limits are absorbed automatically instead of surfacing to your users.

Get API key Back to docs