# Ошибки

Формат ошибок, все коды ответов, ошибки в потоке, повторные запросы и отладка.

## Формат

```json
{
  "error": {
    "code": 400,
    "message": "invalid chat completion request",
    "metadata": { "fields": { "messages": "messages must be a non-empty array" } }
  }
}
```

- `code` совпадает с HTTP-статусом.
- `message` — на английском. Когда провайдер отклоняет запрос (`4xx`), передается его сообщение без частей, которые называют провайдера или ссылаются на него; при лимите частоты (`429`) или сбое (`5xx`) провайдера сообщение — роутера.
- `metadata.provider_name` называет регион провайдера, который дал сбой: `global` или `ru`.
- `metadata.fields` для ошибок проверки `400` сопоставляет каждое неверное поле с его проблемой.

## Коды ответов

| Статус | Когда                                                                                                                                          | Повторять?                             |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `400`  | Неверное тело; неизвестная модель (`model … is not available`); нет маршрута для модели и запроса (`no route of …`); провайдер отклонил запрос | Нет: исправьте запрос                  |
| `401`  | API-ключ неверный, отключен, истек или отозван                                                                                                 | Нет                                    |
| `402`  | Не хватает PnP или исчерпан бюджет ключа или пространства                                                                                      | После пополнения                       |
| `403`  | У пространства нет плательщика, оно потеряло к нему доступ или удалено                                                                         | Нет                                    |
| `404`  | `GET /generation`: такой генерации в этом пространстве нет                                                                                     | Нет                                    |
| `409`  | Плательщик пространства сменился во время запроса                                                                                              | Да, сразу                              |
| `413`  | Тело больше 4 МиБ                                                                                                                              | Нет                                    |
| `422`  | Провайдер не смог обработать запрос                                                                                                            | Нет                                    |
| `429`  | Лимит частоты роутера или провайдера                                                                                                           | Да, с задержкой                        |
| `502`  | Провайдер дал сбой до начала ответа                                                                                                            | Да, с задержкой                        |
| `503`  | Роутер не смог подтвердить баланс плательщика, его лимиты недоступны или он перегружен                                                         | Да, с задержкой                        |
| `504`  | Провайдер не ответил вовремя                                                                                                                   | Да, или используйте потоковую передачу |

## Ошибки в потоке

После начала потока статус уже `200`, а ошибка приходит событием с `error` и `finish_reason: "error"`. Подробнее — в разделе [Потоковая передача](/docs/ru/streaming#ошибки-в-потоке).

## Повторные запросы

- Повторяйте `429`, `502`, `503`, `504` и `409` с экспоненциальной задержкой и случайным разбросом.
- Не повторяйте `400`, `401`, `402`, `403`, `413`, `422`: тот же запрос снова завершится ошибкой.
- Ключа идемпотентности нет, повтор — это новый запрос. Ошибка, которую провайдер вернул до начала ответа, не оплачивается; после тайм-аута посреди ответа оплачивается сгенерированная часть. Если сомневаетесь, посмотрите `billable` у попыток в `GET /api/v1/generation`.
- Лучше, чем повторять запрос к той же модели: укажите резервные модели в `models`, см. [Модели и маршрутизация](/docs/ru/models-and-routing#резервные-модели).

## Отладка

- В каждом ответе есть заголовок `X-Request-Id`. Укажите его, когда обращаетесь в поддержку.
- У генерации есть ID (`id` в ответе, `X-Generation-Id` в потоке). `GET /api/v1/generation?id=gen-…` показывает ее состояние, токены, стоимость и каждую попытку со статусом, см. [GET /generation](/docs/ru/api/generation).
- Логи кабинета показывают то же самое для каждого вызова, а при включенном логировании содержимого — еще и запрос с ответом.