# Errors

> OpenAI and Anthropic error envelopes, the codes, what to do about them and which requests to retry.

An error comes in the envelope of the format you sent the request in — the way
your SDK understands it. Include `request_id` when contacting support; it also
comes in the `x-request-id` header of every response.

Every endpoint except `/v1/messages` uses the OpenAI envelope:

```json
{"error": {"message": "...", "type": "...", "code": "...", "param": "...", "request_id": "req_..."}}
```

`/v1/messages` uses the Anthropic envelope; our `code` and `param` are extra
fields inside `error`, and `request_id` is at the top level:

```json
{"type": "error", "error": {"type": "not_found_error", "message": "...", "code": "model_not_found"}, "request_id": "req_..."}
```

The `param` field is present only when the error concerns a specific parameter.
`error.type` in the Anthropic envelope depends only on the HTTP status:
400 — `invalid_request_error`, 401 — `authentication_error`,
402 — `billing_error`, 403 — `permission_error`, 404 — `not_found_error`,
413 — `request_too_large`, 429 — `rate_limit_error`, 500 and 502 — `api_error`,
503 — `overloaded_error`.

## Error codes

| HTTP | code | What it means |
| --- | --- | --- |
| 400 | `invalid_request` | Malformed request body (no `model`, broken JSON) — check the parameters. A provider rejection the gateway could not classify uses the same code; the HTTP status is then the provider's (4xx). |
| 400 | `unsupported_parameter` | A request parameter is not supported — its name is in the param field. Remove it and retry. See [Request parameters](https://ai-seller.vibe-codes.ru/en/docs/params). |
| 400 | `unsupported_value`, `invalid_value` | The model's provider rejected a parameter value; the parameter name is in the param field when it could be determined. |
| 400 | `context_length_exceeded` | The request does not fit the model's context window. The message starts with “Prompt is too long:” — Claude Code uses it to trigger context compaction. |
| 400 | `content_policy_violation` | The model's content policy rejected the request — change the prompt. |
| 400 | `invalid_image` | The model rejected the reference image — try a different one. |
| 401 | `invalid_api_key` | Key missing, not found or revoked — check the Authorization header. |
| 402 | `insufficient_quota` | Balance exhausted — top up your account. If the remainder is held by requests in progress, retry once they finish. |
| 403 | `spend_limit_exceeded` | This key hit its spend limit — raise the limit or create a new key. |
| 404 | `model_not_found` | The model does not exist, is disabled, is not available to your account or does not fit the endpoint (an image model on chat) — check GET /v1/models with your key. |
| 404 | `not_found` | Unknown endpoint, video job not found or the video is not ready yet. |
| 413 | `invalid_request` | The request body exceeds the limit — see [Limits](https://ai-seller.vibe-codes.ru/en/docs/limits). |
| 422 | `generation_failed` | The model returned no image. Retry the request or rephrase the prompt. |
| 429 | `rate_limit_exceeded` | Too many concurrent requests on your account, or the model is overloaded at the provider. Retry after the pause in the `Retry-After` header. |
| 500 | — | Internal gateway error (`type: server_error`, no `code`). Retry; if it persists, contact support with the `request_id`. |
| 502 | `upstream_unavailable` | The model's providers are temporarily unavailable — retry later. |
| 503 | `service_unavailable` | Service under maintenance or temporarily unavailable — retry later. |
| 503 | — | The model has no available routes right now (`type: server_error`, no `code`) — retry later or pick another model. |

## Retries

Retrying makes sense for 429, 500, 502, 503 and 422. Other errors will not go
away on retry — fix the request, key or balance first.

- On `429` wait for the pause in the `Retry-After` header; without it, use
  exponential backoff (1, 2, 4… seconds). The OpenAI and Anthropic SDKs do this
  themselves.
- An error that arrives as an event mid-stream is also a reason to retry the
  whole request (see [Streaming](https://ai-seller.vibe-codes.ru/en/docs/streaming)).

> Stuck? Email us at support@example.com with the `request_id` from the response.