Коды ошибок

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

Ошибка — это JSON с объектом error из трёх полей:

code

Стабильный код вида ERR_…. По нему выбирайте, что делать.

message

Текст для показа человеку. Он на английском, формулировка может меняться: не разбирайте её программой.

details

Подробности: что именно не так и что исправить. Поле может быть пустым.

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "ERR_INVALID_REQUEST",
    "message": "The reference image is no longer available. Upload the file again.",
    "details": {
      "reason": "reference_unavailable",
      "input_index": 0,
      "retryable": false
    }
  }
}

02Справочник кодов

Строки можно отфильтровать по статусу и найти по слову. Ответы 429 и 503 содержат заголовок Retry-After в секундах.

03Ошибки доступа

Эти ответы общие для всех методов с ключом. Не повторяйте запрос с тем же ключом: повторные 401 и 403 с одного IP-адреса приводят к блокировке на время (подробнее — Лимиты). Как хранить и менять ключи — Ключи и вход.

04Ошибки запроса

Эти отказы приходят до списания. Генерация не начинается, деньги не тратятся.

05Временные отказы

503 значит, что запрос сейчас принять нельзя. Смотрите details.reason:

Иногда приходит 503 ERR_INTERNAL с пустым details: зависимый сервис временно недоступен. 5xx сам по себе не говорит, принят ли запрос: сверяйтесь с заданием по ключу повтора.

06Ожидание и повторы

• Ответы 429 и 503 содержат Retry-After в секундах. Ждите не меньше, а при опросе заданий — не меньше большего из Retry-After и details.min_interval_seconds.
• Повторяйте ограниченное число раз и добавляйте небольшую случайную задержку, чтобы процессы не стучались одновременно.
• 400, 401, 402, 403, 404 не повторяйте без изменений: сначала исправьте причину.
• Если ответ потерялся, на запрос пришёл 500 или истёк тайм-аут, не создавайте новое задание: повторите тот же запрос с тем же ключом повтора (Повтор без двойного списания).

07Ошибки после приёма задания

Если запрос принят (202), а картинка не получилась, это не HTTP-ошибка. GET /creations/{id} отвечает 200 со статусом failed и строкой error. Сумма возвращается на баланс сама.

"The image or prompt was rejected by the safety filter. Try a different image or rephrase the prompt."
"The source image was rejected. Try a different photo."
"Generation failed. Please try again."
"Nothing was rendered for this request. Describe the image you want in the prompt, or attach the source photo it refers to."
"Generation timed out."
"The reference image is no longer available. Upload the file again."
"Could not download the reference image. Please try again later."
"The service is temporarily unavailable. Please try again later."
"Generation failed."

• Отказ по правилам безопасности: измените промпт или возьмите другую картинку.
• «Nothing was rendered…»: опишите нужную картинку в промпте или приложите образец, на который он ссылается.
• «The reference image is no longer available…»: загрузите файл заново и замените file_id.
• Таймаут, временная недоступность, общий сбой: повторите ограниченное число раз. Если сбои повторяются, пришлите в поддержку id задания.

Чтобы намеренно создать новую картинку после failed, возьмите новый ключ повтора: прежний ключ задание не перезапустит, а повтор с ним вернёт сохранённый ответ 202 с тем же id. Новая попытка оплачивается как обычно и возвращается при неудаче.

08Причина сбоя для программ

С 24 сентября 2026 года неудачное задание содержит ещё и объект failure: в GET /creations/{id} и в вебхуке creation.failed. Он есть только при status: "failed", поэтому при разборе считайте его необязательным.

{
  "id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "status": "failed",
  "error": "The image or prompt was rejected by the safety filter. Try a different image or rephrase the prompt.",
  "failure": {
    "type": "declined",
    "code": "content_policy",
    "retryable": false
  }
}

declined

Причина в самом запросе: в промпте, образце или входных данных. Тот же запрос даст тот же результат: измените его.

error

Причина на стороне сервиса. Тот же запрос можно отправить снова, если retryable не равен false.

Стройте логику по failure.type и failure.code, а не по тексту error: он для показа, и формулировка может меняться. Список кодов пока закрыт, но новые могут появиться: незнакомый код обрабатывайте по его failure.type.

FAQЧастые вопросы