# Errors

> HTTP status codes and error shapes from the Vikey API, and how to handle them.

## Error shape

OpenAI-format endpoints (`/v1/chat/completions`, `/v1/responses`, `/v1/models`):

```json
{
  "error": {
    "message": "Model 'nope/nope' not found (request id: req_01ba...)",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "request_id": "req_01ba..."
  }
}
```

Anthropic-format endpoint (`/v1/messages`):

```json
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Model 'nope' not found (request id: req_2062...)",
    "request_id": "req_2062..."
  }
}
```

Include the `request_id` when you contact support. With it we can trace your request.

## HTTP status

| Status | Example message | Meaning | What to do |
| --- | --- | --- | --- |
| `400` | `model is required`, `messages is required` | The request is incomplete or malformed | Fix the request body |
| `400` | `Model '...' matches several models` (`ambiguous_model`) | A short name matches several providers | Use one of the full ids in the message |
| `401` | `API key is required`, `Invalid API key` | No key sent, or a wrong key | Check the header and copy the key again |
| `402` | `Insufficient balance` | The balance does not cover this request's estimated cost | [Top up](/en/account/top-up/), or lower `max_tokens` |
| `403` | `API key is inactive` | The key is turned off | Turn it on again in **API Keys** |
| `403` | `This account has been blocked` (`account_blocked`) | The account is blocked | Contact support |
| `404` | `Model '...' not found` (`model_not_found`) | Wrong model id, or the model is inactive | Get the id from `GET /v1/models` |
| `429` | Passed on from the model | The target model is rate limiting | Wait a moment and retry |
| `502`, `503` | `The model's supplier is currently unavailable` | The model has a problem on the provider side | Retry shortly, or use another model. [Vikey Auto](/en/models/vikey-auto/) moves to the next level automatically. |

## Handling errors in your app

- Retry `429`, `502` and `503` automatically, with growing delays.
- Do not retry `400`, `401`, `402`, `403` and `404` automatically. The result stays the same until the cause is fixed.
- For `402` in an app used by many people, show a clear message to the app's admin so the balance is topped up quickly.

Source: https://docs.vikey.ai/en/api/errors/