Ошибки, лимиты, биллинг

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

Конверт совпадает с OpenAI, поэтому обработчики ошибок в существующем коде менять не нужно:

{
  "error": {
    "message": "Rate limit reached for requests. Limit: 60 requests/min.",
    "type": "rate_limit_exceeded",
    "param": null,
    "code": "rate_limited"
  }
}

Коды состояний

HTTP	type	Что произошло и что делать
400	invalid_request_error	Неверный параметр: размер вне списка модели, файл модели, которая не умеет файлы. Сверьтесь с каталогом
400	content_filter	Запрос отклонён фильтром апстрима. Переформулируйте промпт
401	invalid_request_error	Ключ отсутствует, отозван или неверный
402	insufficient_quota	Не хватает денег на балансе. Пополнить в кабинете
403	invalid_request_error	У ключа нет нужной области доступа
404	invalid_request_error	Модель не найдена; в сообщении будут похожие идентификаторы
429	rate_limit_exceeded	Превышен лимит запросов в минуту
500	api_error	Наша ошибка. Повторить с экспоненциальной паузой
502	api_error	Апстрим не ответил. Повторить или взять другую модель

Лимит запросов

По умолчанию — 60 запросов в минуту на ключ, скользящее окно в минуту. При превышении приходит 429 и два заголовка:

retry-after: 37
x-ratelimit-limit-requests: 60

retry-after — сколько секунд ждать. Официальные OpenAI SDK читают его сами и делают backoff, самописному клиенту это стоит реализовать.

Лимит считается по ключу, а не по аккаунту: если нужно больше параллелизма, разложите нагрузку на несколько ключей.

Биллинг

• Деньги списываются с единого баланса Mixen — того же, что у бота и кабинета.
• Списание происходит по факту выполнения. Неудачная генерация (failed, 502, зависшая видеозадача) не оплачивается.
• Цена берётся из каталога на момент запроса. Формулу и единицы смотрите в разделе Модели и цены.
• Расход по чату виден в поле usage ответа; в стриминге он приходит финальным чанком при stream_options: {"include_usage": true}.

Ретраи

Разумная стратегия для продакшена:

1. 429 — ждать retry-after, потом повторить.
2. 500 и 502 — до трёх попыток с паузой 1, 2, 4 секунды.
3. 400, 401, 402, 403, 404 — не повторять, это ошибка запроса или счёта; повтор даст тот же ответ и потратит лимит.

Таймауты

Ставьте таймаут HTTP-клиента не меньше 120 секунд для картинок и длинных чатов: обрыв на стороне клиента не отменяет уже начатую генерацию, и деньги за неё спишутся. Для видео и музыки таймаут не нужен вовсе — они асинхронные.