Ошибки

Любая ошибка — HTTP-статус и один конверт (схема Error). Ветвитесь по error.type и error.code; message подсказывает, что делать, но его формулировка может меняться.

JSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "capability_mismatch",
    "message": "the model does not support this value",
    "detail": [{"path": "aspect_ratio", "reason": "unsupported_value", "allowed": ["1:1", "16:9", "9:16"]}]
  }
}

Тип — что делать программе

`type`	Статусы	Что делать
`invalid_request_error`	400, 405, 413, 415	исправить запрос по `detail[]`; `405` — у адреса нет такого метода (`Allow`); `415` — тело не `application/json` (у загрузки файла и транскрибации — не `multipart/form-data`)
`authentication_error`	401	проверить ключ
`billing_error`	402	пополнить баланс или поднять лимит; повтор не поможет
`permission_error`	403	не тот вид ключа, действие только в кабинете, роли не хватает (причина — в `detail[].reason`), не сошлась подпись ссылки на файл или аккаунт либо ключ заблокирован службой поддержки (`account_blocked`, `key_blocked` — повтор не поможет, напишите в поддержку)
`not_found_error`	404, 410	нет такой модели, задачи, файла или адреса; `410` — срок файла вышел
`conflict_error`	409	тот же `Idempotency-Key` с другим запросом
`rate_limit_error`	429	подождать `Retry-After` и повторить
`model_error`	502, 503, 504	модель не справилась (`502 generation_failed`), неизвестная ошибка (`502 unknown_error`), её сейчас некому выполнить (`503 model_unavailable`, с `Retry-After`) или ответа не дождались (`504`: запрос мог выполниться — повтор с тем же `Idempotency-Key` вернёт задачу), сервер занят большими запросами (`503 overloaded`, с `Retry-After`), идут плановые работы (`503 maintenance`, срок — в `ends_at`) — повторить позже
`server_error`	500	наша ошибка; повторить, при повторении — написать нам

Код — что случилось

code — закрытый словарь (схема ErrorCode): invalid_request, invalid_input (файл или значение отвергнуты), capability_mismatch (модель не принимает поле или значение), content_policy, invalid_api_key, account_blocked (аккаунт заблокирован службой поддержки: новые запросы не принимаются, чтение задач и результатов работает), key_blocked (ключ заблокирован службой поддержки), insufficient_balance, key_spend_limit_exceeded, member_spend_limit_exceeded, invalid_signature, unauthorized (сессия кабинета недействительна), forbidden (не тот вид ключа или не хватает роли), not_found (нет такого адреса), model_not_found, job_not_found, file_not_found, file_expired, idempotency_key_conflict, secret_unavailable (секрет ключа показать нельзя — создайте новый), rate_limited, generation_failed, unknown_error (неизвестная ошибка), model_unavailable, no_channel_matches (routing_options отсекли все каналы), storage_limit_exceeded (загрузки POST /v1/files заняли квоту), overloaded (сервер занят большими запросами), maintenance (плановые работы), internal_error.

Деталь — что поправить

detail[] — когда известно, что именно не так: path — поле запроса так, как вы его прислали (aspect_ratio, references[1], elements[0].images[1]), reason — причина из словаря (схема DetailReason: required, unsupported_field, unsupported_value, incompatible_value, out_of_range, too_long, too_many_items (файлов или элементов больше, чем принимает модель, — в allowed предел), unsupported_format, too_large…), allowed — что было бы принято.

Поле, которого у ручки нет, — 400 invalid_request с {"path": "<поле>", "reason": "unsupported_field"}. Значение, которое у модели ничего не меняет, принимается молча: её умолчание, auto, поле, которого у модели нет, с тем значением, которое она и так даёт (Запросы и ответы).
no_channel_matches — routing_options отсекли все каналы модели; detail[].reason — not_selected, above_max_price или fallback_disabled (Каналы).
Модель другой модальности — 400 invalid_request с подсказкой пути: {"path": "model", "reason": "wrong_endpoint", "allowed": ["/v1/videos"]}.
Причина, которую назвала сама модель после приёма, приходит той же формой в error проваленной задачи (у контентного фильтра — content_policy_category). Чаще её нет — тогда только code и message.

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

`code`	Статус	Что случилось	Что делать
`invalid_input`	400	модель отвергла входные данные: параметр, файл, формат, размер или длительность	исправить по `detail[]`, без него — сверить запрос со схемой модели (`GET /v1/models/{id}`); повтор того же запроса не поможет
`content_policy`	400	сработал контентный фильтр: после отказа фильтра запрос пробует ещё один канал по пресету, и тот тоже отказал или не вернул результата	переписать описание или заменить файлы; деньги не списаны
`generation_failed`	502	модель приняла запрос и не справилась: ответила без результата, задача у канала завершилась неудачей	повторить; деньги не списаны
`unknown_error`	502	неизвестная ошибка: ответ, который мы не смогли разобрать, или сбой на нашей стороне; подробностей нет	повторить; деньги не списаны; мы разбираем такие случаи
`model_unavailable`	503	каналы модели сейчас недоступны: на паузе, перегружены, упёрлись в лимит, не ответили вовремя или подходящих каналов нет	повторить позже или выбрать другую модель

unknown_error появился 08.10.2026: часть отказов, которые раньше приходили как 503 model_unavailable (сбой на нашей стороне, ответ, который мы не разобрали), теперь приходит как 502 unknown_error. Если программа повторяет запрос по коду model_unavailable, повторяйте и unknown_error.

Если каналы отказали по-разному, код — по главной причине: отказ контентного фильтра или окончательный отказ входных данных важнее последующих сбоев других каналов. После отказа фильтра и сбоя соседнего канала придёт content_policy, а не generation_failed.

Плановые работы — `503 maintenance`

На время плановых работ новые запросы (POST, PUT, PATCH, DELETE) получают 503 с code: "maintenance", заголовком Retry-After и сроком в конверте: ends_at — до какого времени работы, reason — что делаем.