Reference / Errors

# Errors

Standardized across every provider, with a request ID on every failure and explicit retry semantics.

## Error shape

```
{
  "error": {
    "type": "rate_limit",
    "message": "key requests limit of 600 per minute exceeded; retry in 2s",
    "code": "rate_limit",
    "param": "requests",
    "request_id": "req_01J9F3KJ2MQ8ZV5T7XB0N4A6WD",
    "retriable": true
  }
}
// plus X-Request-Id on every response; on a 429 also Retry-After
// and X-RateLimit-* (see Rate limits & quotas)
```

| HTTP | Type · code | Retry | Gateway behavior |
| --- | --- | --- | --- |
| 400 | invalid_request | no | Malformed body or parameter; param names the field. A provider 4xx arrives as code provider_http_4xx |
| 400 | invalid_requestcode: unsupported_parameter | no | A body field the route does not list (voice cloning, callback_url, previous_job_id, provider routing or account fields) is refused, never forwarded |
| 400 | invalid_requestcode: approval_required | no | Management API: the mutation is gated by an approval policy and now waits for a decision; error.approval_request_id names the request |
| 401 | authentication | no | Key missing, malformed, unknown or revoked (code invalid_api_key); same answer for every case |
| 402 | insufficient_funds | no | Hard stop before dispatch: no wallet or the hold was refused; nothing is charged |
| 402 | insufficient_fundscode: budget_exceeded | no | A blocking budget in scope is exhausted (spent + estimate > amount); param is "budget" and the message names it. Nothing is sent, nothing is charged |
| 403 | permission | no | Your role lacks the permission (management API); an OAuth token outside its scopes gets code insufficient_scope |
| 404 | not_found | no | Model not available to your organization, or unknown resource — never a hint that it exists |
| 409 | invalid_requestcode: idempotency_key_reused | no | The Idempotency-Key was already used with a different request body; param is "Idempotency-Key" |
| 409 | invalid_requestcode: idempotency_in_progress | yes | The original request with this Idempotency-Key is still running; retry after about a second and you get its stored response |
| 422 | capability_unsupported | no | Strict-mode parameter rejection, or code no_eligible_route when hard constraints eliminate every endpoint; no provider contacted |
| 422 | capability_unsupportedcode: operation_unsupported | no | The model is not served on this route (an image model sent to /v1/chat/completions, for example); the message names the route that serves it |
| 429 | rate_limitcode: rate_limit | yes | Your key or organization bucket is empty: param is "requests" or "tokens", Retry-After and X-RateLimit-* say when; nothing is charged and no request is recorded |
| 429 | rate_limitcode: provider_rate_limit | yes | A provider rate-limited the attempt: Retry-After set, then fallback to the next planned attempt within your constraints |
| 500 | internal | no | Unexpected failure; unhandled ones carry retriable: true. Quote request_id to support |
| 502 | provider_error | yes | Provider returned an error; retried on the next planned attempt |
| 503 | overloaded | yes | Provider 502/503/504 or timeout; retried on the next planned attempt. Endpoints whose circuit is open are left out of the plan |

## Idempotency

Send `Idempotency-Key` on any inference call. The key is claimed per organization before the request is written and kept for 24 hours. A second call with the same key and the same body is a replay: the stored status and body come back with `Idempotency-Replayed: true` and the original's `X-Request-Id`, an originally streamed request is replayed as a compact SSE stream ending in the same final frame, and no rate-limit token, wallet hold or charge is consumed. The same key with a different body is `409` `code: "idempotency_key_reused"` (`param: "Idempotency-Key"`); while the original is still in flight it is `409` `code: "idempotency_in_progress"` with `retriable: true` — retry after about a second. Only successful responses are stored, so a request that failed may be retried with the same key.

```
POST /v1/chat/completions
Idempotency-Key: order-8812-summary          # any string unique to the operation, per organization

# first call → 200, X-Request-Id: req_01J9F3KJ…
# same key + same body within 24 h → 200, the stored body, plus
Idempotency-Replayed: true
X-Request-Id: req_01J9F3KJ…                   # the original request

# same key + different body → 409 idempotency_key_reused
# original still running        → 409 idempotency_in_progress
```

Partial streams that disconnect are metered for the usage observed and reconciled against the provider's final report.

Source: https://yelno.ai/docs/errors