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

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

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

Ошибка — код 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 или раздел недоступен через ключ См. Ключи и права
404 Нет такой книги, главы, строки или задачи (или она не ваша) Проверьте id
409 Так сейчас нельзя: глава уже озвучивается, версия книги закрыта, тот же файл уже загружен Подождите или прочитайте detail
422 Перед озвучкой нужно исправить главу (например, голос героя не установлен) или неверные поля запроса Текст — в detail
429 Больше 120 запросов в минуту или слишком много глав в работе Подождите и повторите
5xx, 503 Сервер занят или озвучка не ответила вовремя Повторите через минуту

Повторы

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