Ошибки API и повторные запросы
Читайте статус и тело
Ошибки шлюза используют поля error.code, error.message и error.request_id. Ошибки inference могут приходить с detail в виде строки или объекта. Ответы провайдера могут сохранять собственную структуру.
422: ошибка проверки тела
{"error":{"code":"VALIDATION_ERROR","message":"request_validation_failed","request_id":"49e96e49-dc1b-489e-a025-e4cc8fef1e1f"}}401: отсутствует ключ
{"detail":"missing_api_key"}404: модель не опубликована
{"detail":{"error":"model_not_published"}}При ограничении частоты возможна оболочка с error: "rate_limited", scope: "inference" и retryAfterSeconds. Не предполагается, что любой 429 содержит объект error или detail.
Коды основных операций
| HTTP | Код | Действие |
|---|---|---|
| 400 | model_deprecated, provider_streaming_not_supported, kie_param_fixed | Выберите актуальную модель, отключите неподдерживаемый streaming или исправьте параметры. |
| 401 | missing_api_key, invalid_api_key, unauthorized, key_expired, key_suspended, INVALID_API_KEY | Проверьте заголовок и ключ. Подробности: аутентификация. |
| 402 | insufficient_balance | Проверьте баланс и пополните его перед повтором. |
| 404 | NOT_FOUND, provider_not_resolved, provider_not_configured, model_not_published | Проверьте URL и ID модели. При проблеме конфигурации обратитесь в поддержку. |
| 405 | METHOD_NOT_ALLOWED | Для chat/completions и images/generations используйте POST. |
| 409 | idempotency_in_progress, idempotency_key_released, generation_price_changed | Разберите состояние операции или обновлённую цену до новой отправки. |
| 422 | VALIDATION_ERROR, idempotency_key_reused | Исправьте JSON. Для идемпотентного повтора не меняйте тело. |
| 429 | rate_limited, spend_limit_exceeded | При частотном лимите подождите и повторите. При лимите расходов проверьте настройки ключа. |
| 500 | INTERNAL_SERVER_ERROR | Сохраните сведения о запросе для поддержки. |
| 502 | INFERENCE_SERVICE_UNAVAILABLE, EMPTY_INFERENCE_RESPONSE, provider_unavailable | Возможна ошибка связи шлюза с inference, пустой ответ или ошибка связи с провайдером. |
| 503 | INFERENCE_UNAVAILABLE, provider_unavailable, outcome_not_recorded | Возможны недоступность сервиса или неопределённый результат операции. |
| 504 | INFERENCE_UPSTREAM_TIMEOUT | Истёк срок ожидания ответа inference на чат-запрос. Это не доказательство, что операция не выполнена. |
Таблица не исчерпывает ответы провайдеров. Один HTTP-статус может иметь разные причины. Тайм-аут связи шлюза с сервисом генерации для изображений и видео возвращается как 503, а для чата как 504.
Идентификатор запроса
Сохраняйте X-Request-Id из ответа и error.request_id, если они есть. Идентификатор используется в журналах и помогает разобрать обращение. Ранний отказ ограничения частоты может не содержать этот заголовок.
Когда повторять
- 401, 402 и ошибки параметров: сначала устраните причину.
- При
rate_limitedподождите перед повтором. Увеличивайте паузу между неудачными попытками; используйтеretryAfterSecondsилиRetry-After, если они получены. - После сетевого обрыва, 502, 503 или 504 сначала оцените, мог ли запрос уже начаться. Не повторяйте создание операции бесконтрольно.
- Если уже есть
taskId, проверяйте статус задачи через её GET-маршрут вместо повторного создания.
Заголовок Retry-After может не пройти через обычный маршрут inference. Предусмотрите паузу и без него.
Idempotency-Key
Для Idempotency-Key используйте от 1 до 128 печатных ASCII-символов без пробелов. Неверный формат отклоняется шлюзом с HTTP 400 и кодом INVALID_IDEMPOTENCY_KEY. Для медиа-задач с отложенной обработкой повтор привязан к ID API-ключа и ключу идемпотентности: он может вернуть исходный taskId или успешный результат без нового вызова провайдера. Это условный контракт, а не гарантия для любого запроса.
Для такого повтора сохраняйте исходный API-ключ, Idempotency-Key и неизменное тело. Не переносите эту гарантию на чат. Если ключ не передан, отложенная генерация создаёт его сама; потеряв ответ, клиент не сможет полагаться на знание этого ключа.
Частые вопросы
Безопасен ли повтор после 504?
Нет общей гарантии. Провайдер мог начать операцию до тайм-аута шлюза. Для чата повтор может стать отдельным платным запросом.
Почему один 429 требует паузы, а другой проверки ключа?
rate_limited ограничивает частоту. spend_limit_exceeded означает исчерпание лимита расходов API-ключа.
Что приложить к обращению?
HTTP-статус, код ошибки, ID модели, время и идентификатор запроса, если он есть. Ключ и конфиденциальное содержимое не отправляйте. Контакт: помощь.
Обновлено