Ошибки

Требуется оплата

Недостаток средств компании/аккаунта возвращает HTTP 402 Payment Required в OpenAI-совместимой структуре:

{
  "error": {
    "message": "Insufficient account balance.",
    "type": "payment_required",
    "code": "insufficient_balance"
  }
}

Та же стабильная причина/код сохраняется в истории запросов. Запрос 402 отклонён до выполнения у поставщика; не повторяйте его автоматически, пока не устранена нехватка средств или ограничение расходов.

Отказ по списку разрешённых IP

Если API-ключ действителен, но исходный адрес не входит в эффективный личный или корпоративный API-список, Model Gate отклоняет запрос до выполнения у поставщика. OpenAI-совместимый ответ использует HTTP 403 и код ip_not_allowed. Anthropic-совместимый ответ использует структуру Anthropic с HTTP 403 и authentication_error. Не повторяйте с того же запрещённого адреса: измените список или отправьте запрос с разрешённого IP.

Повторяйте 429 после Retry-After. Для безопасных операций чтения допустим ограниченный backoff после 500, 502, 503 или 504. Не переносите это правило вслепую на платные inference POST. Не повторяйте автоматически ошибки валидации, аутентификации, баланса или отсутствия ресурса.

Сопоставляйте ответ с журналом запросов по публичному идентификатору из X-Request-ID.

Ошибки после отправки заголовков потока

Поток SSE может завершиться ошибкой после отправки HTTP200. В ответе тогда появляется совместимое с протоколом событие ошибки; в истории запросов сбой может быть записан независимо от первоначального HTTP-статуса. Подробности ошибки поставщика могут заменяться безопасным сообщением. Отсутствующие данные об использовании после обрыва потока означают неизвестное значение, а не оценку по размеру ответа. Сохраните идентификатор запроса и проверьте частичный результат перед повтором; обращайтесь в поддержку, не передавая ключи или конфиденциальное содержимое.

Ошибки специализированного Images API

Для собственных ошибок проверки и управления Images использует оболочку image_request_error. Сохраняйте исходный Idempotency-Key, точный запрос и идентификатор операции. Даже успешный HTTP-ответ может содержать конечный статус операции; проверяйте status и error_code. Значения outcome_unknown или review_required означают необходимость остановиться и обратиться к оператору, а не отправить новый POST. При retrieval_failed разрешён только явный повтор скачивания уже существующего результата. Ошибки 409 idempotency_conflict и 422 image_quote_changed не разрешают временно сменить ключи и попробовать снова. См. актуальный справочник состояний и ошибок Images.

Подробности ошибки поставщика и проверка сессии

Тело ошибки поставщика не обязательно передаётся без изменения. Решение о показе сообщения принимается по нормализованному тексту ошибки, независимо от модели, поставщика и HTTP-статуса. Непроверенные сообщения скрываются за безопасным ответом; очистка конфиденциальных данных и формат соответствующего протокола сохраняются. HTTP-статус и поля ошибки полезны для диагностики, но не выбирают другое правило раскрытия для того же нормализованного текста.

Недопустимый идентификатор сессии вызывает ошибку валидации: исправьте поле, а не повторяйте запрос без изменений. Уже заданная распознанная сессия в metadata.user_id принимается с приоритетом session_id, X-Session-ID, распознанная сессия в метаданных, prompt_cache_key, затем начальное содержимое. Разные переданные значения не вызывают ошибку несовпадения сессий. Обычный идентификатор пользователя сохраняется, не превращаясь в идентификатор диалога. Маршрут, использующий это занятое поле, не может одновременно вставить управляемую сессию; внешняя привязка в таком случае не обещается. Неверные типы метаданных или повторяющиеся ключи объекта по-прежнему могут вызывать ошибку валидации на маршруте с передачей сессии через метаданные. Остальные метаданные сохраняются. Наличие идентификатора сессии не доказывает, что платный запрос с тайм-аутом не был принят. Сохраните X-Request-ID и проверьте существующий запрос перед повтором.

Передача сессии использует нативный протокол настроенного подключения и не требует отдельного получателя или его подтверждения. Клиентский X-Session-ID принимается на входе шлюза, но не является универсальным заголовком для всех upstream. Передача сессии не гарантирует выбор определённого аккаунта поставщика или попадание в кеш и не разрешает повтор платного запроса.

Явные ошибки поставщика Images (14.11.2)

Распознанные конечные ошибки Images используют status: failed и безопасный объект error. Коды image_generation_failed и image_provider_error возвращают HTTP 502 при создании / чтении результата; invalid_image_request и content_policy_violation — 400; rate_limit_exceeded — 429. Идентификатор принятой операции и её URL сохраняются в ответе. Чтение состояния использует HTTP 200 с ошибочной операцией. Тело с ошибкой при HTTP 200 поставщика также означает ошибку генерации.

billing_review_required отдельно описывает необходимость проверки расчёта. Не делайте вывод о нулевой стоимости из ошибки генерации и не повторяйте платный POST автоматически. Сохраняйте исходный ID операции и Idempotency-Key. См. операции изображений. Произвольные сообщения и секреты поставщика в этих объектах ошибки не раскрываются.