Коды ошибок API

На этой странице

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

При неудачном запросе API возвращает код состояния 4xx или 5xx и тело ответа:

json

{
  "error": {
    "code": "invalid_request",
    "message": "Модель gpt-image-2 не поддерживает соотношение сторон 21:9",
    "type": "invalid_request_error"
  }
}

Поле	Описание
`code`	Стабильный код ошибки — по нему программа должна определять тип ошибки
`message`	Понятное человеку описание (пока на китайском); текст может меняться, поэтому не используйте его в логике программы
`type`	Общая категория ошибки: `invalid_request_error`, `authentication_error`, `rate_limit_error` или `api_error`

Список кодов ошибок

HTTP-код	`code`	Значение	Что делать
400	`invalid_request`	Параметр отсутствует или имеет неверный формат, режим/соотношение сторон/качество не поддерживаются, не удалось скачать референс или его адрес небезопасен	Исправьте параметры по `message`; не повторяйте запрос без изменений
401	`invalid_api_key`	Ключ не передан, неверен, истёк или отозван либо аккаунт заблокирован	Проверьте заголовок `Authorization`, при необходимости создайте новый ключ
402	`insufficient_points`	Недостаточно баллов; задача не создана, баллы не списаны	Купите баллы и повторите запрос
403	`invalid_signature`	Подпись ссылки на скачивание результата недействительна или истекла	Заново вызовите `GET /tasks/{id}`, чтобы получить новую ссылку
404	`model_not_found`	Модель не существует, отключена или её тип не соответствует методу	Заново запросите список моделей
404	`task_not_found`	Задача не существует или не принадлежит текущему аккаунту	Проверьте ID задачи
404	`file_not_found`	Файл результата удалён	Восстановить нельзя — сгенерируйте заново
409	`idempotency_conflict`	Запрос с тем же `Idempotency-Key` ещё обрабатывается	Подождите несколько секунд и повторите с тем же значением
429	`rate_limited`	Превышен лимит запросов в минуту	Подождите время из заголовка ответа `Retry-After` и повторите
429	`concurrency_limit`	Достигнут лимит одновременно выполняемых задач	Подождите время из `Retry-After` (10 секунд) или дождитесь завершения текущих задач, затем отправляйте новые
500	`server_error`	Внутренняя ошибка сервера	Повторите позже; для методов отправки передавайте тот же `Idempotency-Key`
502	`upstream_error`	Сбой внешнего сервиса (например, не удалось улучшить промпт; баллы возвращены)	Повторите позже

Стратегия повторов

Можно повторять: 409, 429, 500, 502 и сетевые тайм-ауты. Используйте экспоненциальную задержку (например, 2, 4, 8 секунд); для 429 в первую очередь ориентируйтесь на Retry-After.
Не повторяйте: 400, 401, 402, 403, 404 — сначала исправьте запрос.
При повторе отправки используйте тот же `Idempotency-Key` — тогда, даже если первый запрос на самом деле прошёл успешно, вторая задача не будет создана и баллы не спишутся повторно. См. Идемпотентная отправка.

Ответ 202 метода отправки означает лишь, что задача создана. Проблемы, возникшие во время генерации, не возвращаются как HTTP-ошибки, а отражаются в самой задаче: GET /tasks/{id} возвращает status: "failed" и error.message. Баллы за неудавшиеся задачи возвращаются автоматически.

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

Список кодов ошибок

Стратегия повторов

Ошибки задач и ошибки API