# Ошибки и лимиты

Коды ответов, формат ошибки, повторы и защита от двойной постановки.

## Формат ошибки

Ошибка — код HTTP и JSON с полем `detail`: текст для человека (по-русски) или объект с подробностями.

```json Ответ 402
{"detail": "Не хватает знаков: нужно 15 488, на балансе 1 200. Пополните баланс."}
```

```json Ответ 409
{"detail": {"message": "Эта книга уже загружена: «Вечер в саду»", "duplicate": {"id": "01a134d0-…", "title": "Вечер в саду"}}}
```

## Коды

| Код | Что значит | Что делать |
|---|---|---|
| `400` | Неверные данные запроса | Прочитайте `detail` и поправьте запрос |
| `401` | Нет ключа, ключ неверный или отозван | Проверьте заголовок `x-api-key` |
| `402` | Не хватает знаков: на балансе, в лимите ключа или в бюджете книги | Пополните баланс или поднимите лимит ключа |
| `403` | Ключу не хватает прав, запрос не с разрешённого IP или раздел недоступен через ключ | См. [Ключи и права](/developers/auth) |
| `404` | Нет такой книги, главы, строки или задачи (или она не ваша) | Проверьте id |
| `409` | Так сейчас нельзя: глава уже озвучивается, версия книги закрыта, тот же файл уже загружен | Подождите или прочитайте `detail` |
| `422` | Перед озвучкой нужно исправить главу (например, голос героя не установлен) или неверные поля запроса | Текст — в `detail` |
| `429` | Больше 120 запросов в минуту или слишком много глав в работе | Подождите и повторите |
| `5xx`, `503` | Сервер занят или озвучка не ответила вовремя | Повторите через минуту |

## Повторы

- Сеть оборвалась после `POST /chapters/{id}/render` — не страшно: добавьте заголовок `Idempotency-Key: <ваш id>`,
  и повтор с тем же ключом вернёт ту же задачу, а не поставит вторую.
- Повтор того же текста тем же голосом никогда не списывается второй раз: звук берётся готовым.
- `429` и `5xx` повторяйте с паузой: 5 с, 20 с, минута.