Справочник кодов ошибок

Значения типичных HTTP-статусов, ошибок асинхронных задач и программных кодов платформы.

Ответ ошибки обычно содержит HTTP-статус и программный код в теле. Сначала проверьте HTTP-статус, затем фактические type, code и message. Поля могут различаться между протоколами и сервисами.

Для диагностики по симптомам сначала прочитайте Ошибки и диагностика. Эта страница объясняет ошибки, но не заменяет описание ответа конкретного Endpoint.

HTTP-статусы

HTTP-статус	Типичное значение	Частые причины	Рекомендуемое действие
`400`	Неверный запрос	JSON, обязательные поля, типы, формат файла или ввод не соответствуют требованиям	Исправьте запрос по ошибке, не повторяя без изменений
`401`	Ошибка аутентификации	API Key отсутствует, недействителен или Header не соответствует протоколу	Проверьте Bearer или специальный Header, замените недействительный Key
`403`	Недостаточно прав или квоты	Учётная запись, Key, права на модель, диапазон IP или квота не удовлетворяют запросу	Проверьте ограничения учётной записи и Key и доступность модели
`404`	Ресурс не существует	Нет Endpoint, ID модели, ID задачи или Video ID	Проверьте итоговый URL, ID ресурса и учётную запись владельца
`429`	Запрос ограничен	Достигнут лимит частоты, параллелизма, квоты или мощности сервиса	Снизьте нагрузку, ограниченно повторите; при постоянном сбое сохраните Request ID
`500`	Ошибка обработки	Сбой преобразования запроса, подсчёта токенов, цен или обработки платформой	Сохраните обезличенную ошибку и Request ID, ограниченно повторите позже
`502`	Ошибка вышестоящего шлюза	Неверный ответ сервиса или невозможность пересылки шлюзом	Ограниченно повторите; при постоянном сбое обратитесь в поддержку
`503`	Сервис временно недоступен	Перегрузка, обслуживание или отсутствие мощности платформы либо сервиса	Увеличивайте интервалы повторов, не отправляйте частые запросы постоянно
`504`	Тайм-аут запроса	Сервис обрабатывает запрос дольше ожидания шлюза	Сохраните Request ID; для асинхронной задачи сначала проверьте исходное состояние

HTTP-статус не определяет причину сам по себе

404 может означать отсутствие пути, модели или задачи. 429 может быть вызван частотой, параллелизмом, квотой или мощностью сервиса. Учитывайте фактическое тело ошибки и Request ID.

Типичные оболочки ошибок

OpenAI-совместимые интерфейсы обычно помещают сведения в объект error:

{
  "error": {
    "message": "Конкретная причина ошибки запроса",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Некоторые интерфейсы задач платформы возвращают code и message напрямую:

{
  "code": "task_not_exist",
  "message": "Запрошенный ID задачи не существует"
}

Не предполагайте одинаковую оболочку ошибок во всех интерфейсах. Изучите соответствующий API Reference и допускайте отсутствие необязательных полей.

Ошибки асинхронных задач

Задачи Midjourney

`code`	HTTP-статус	Значение для клиента	Рекомендуемое действие
`1`	`200`	Задача успешно отправлена	Сохраните ID и получайте прогресс через интерфейс запроса
`4`	`400`	Неверные параметры	Проверьте Prompt, тип операции и обязательные поля
`21`	`200`	Такая задача уже существует	Используйте возвращённый ID, не создавая повторно
`22`	`200`	Задача в очереди	Сохраните ID и проверьте позже
`23`	`429`	Очередь задач заполнена	Снизьте частоту отправки и повторите позже
`24`	`400`	Prompt не прошёл проверку содержимого	Измените Prompt и отправьте заново
`3`	`403`	Запрос временно нельзя отправить	Сохраните ошибку, повторите позже или обратитесь в поддержку
`30`	`429`	Мощность обработки текущей группы исчерпана	Снизьте параллелизм и повторите позже

Пример успешной отправки:

{
  "code": 1,
  "description": "Успешно отправлено",
  "result": "TASK_ID"
}

Пример очереди:

{
  "code": 22,
  "description": "В очереди, впереди ещё 2 задачи"
}

Задачи платформы

`code`	HTTP-статус	Значение для клиента	Рекомендуемое действие
`task_not_exist`	`404`	Задача отсутствует или принадлежит другой учётной записи	Проверьте ID задачи, API Key и узел запроса
`quota_not_enough`	`403`	Квоты недостаточно для создания	Проверьте квоты учётной записи и токена, не повторяйте без изменений
`invalid_api_platform`	`400`	Неверный тип платформы в запросе	Исправьте параметр платформы или протокола
`fail_to_fetch_task`	Определяется статусом сервиса	Не удалось получить актуальное состояние от источника задачи	Сохраните ID и ограниченно повторите позже

Программные коды платформы

`code`	Типичный HTTP-статус	Значение для клиента	Рекомендуемое действие
`invalid_request`	`400`	Неверный формат или параметры	Проверьте JSON, обязательные поля и типы
`read_request_body_failed`	`400`	Не удалось прочитать тело	Проверьте размер тела, соединение и Content-Type
`sensitive_words_detected`	`400`	Ввод не прошёл проверку содержимого	Измените ввод и отправьте заново
`prompt_blocked`	`400`	Prompt заблокирован политикой содержимого	Измените Prompt по сообщению ошибки
`access_denied`	`403`	Запрос отклонён	Проверьте API Key, учётную запись и разрешённые IP
`insufficient_user_quota`	`403`	Недостаточная квота учётной записи	Проверьте баланс или квоту перед запросом
`pre_consume_token_quota_failed`	`403`	Недостаточная квота токена	Проверьте квоту и ограничения текущего Key
`model_not_found`	`404`	Учётная запись не может найти модель	Скопируйте доступный ID из каталога моделей
`convert_request_failed`	`500`	Запрос нельзя преобразовать в целевой протокол	Проверьте Endpoint, протокол и совместимость модели
`count_token_failed`	`500`	Не удалось подсчитать токены запроса	Сохраните обезличенные характеристики и Request ID
`do_request_failed`	`500`	Платформа не выполнила запрос к сервису	Проверьте сеть и ограниченно повторите
`bad_response_status_code`	Определяется статусом сервиса	Сервис вернул нестандартную или неразбираемую ошибку	Сохраните исходный HTTP-статус, обезличенное сообщение и Request ID
`api_not_implemented`	`501`	Endpoint пока недоступен	Проверьте API Reference, используйте уже опубликованный Endpoint

Принципы обработки клиентом

Сохраняйте HTTP-статус, программный код, обезличенное сообщение и Request ID вместе.
Для 400, 401, 403 сначала устраните причину, не повторяя автоматически без изменений.
При 404 проверьте путь и ID, а для асинхронного ресурса — учётную запись владельца.
Для 429, 502, 503, 504 допустимы ограниченные повторы с увеличением интервала.
Перед повтором создания задачи или запроса с побочными эффектами проверьте, не выполнен ли исходный запрос.
Не используйте полный текст ошибки для ветвления: предпочитайте стабильный HTTP-статус и code.

Для сохранения трассировки см. Request ID. Полные рекомендации по диагностике и повтору приведены в Ошибки и диагностика.