Коды ошибок
Формат ошибок API и коды 401, 402, 403, 429 — причины и что делать
Коды ошибок
Формат ошибки
Ошибки возвращаются в формате OpenAI:
{
"error": {
"message": "Недостаточно средств на балансе",
"type": "billing_error",
"code": "insufficient_funds"
}
}Идентификатор запроса
Каждый ответ шлюза — и обычный, и SSE-стрим, и ответ об ошибке — несёт заголовок:
x-request-id: 4f3c1b8e-...Это тот же идентификатор, под которым запрос записан в нашем журнале. Если что-то пошло не так, пришлите его в поддержку: по нему мы найдём конкретный вызов, не разбирая соседние по времени.
Коды шлюза
| Код | Значение | Что делать |
|---|---|---|
401 | Невалидный ключ или истёк его срок жизни | Проверьте ключ; при истёкшем сроке создайте новый в кабинете |
402 | Недостаточно средств на балансе | Пополните баланс. Запрос к провайдеру в этом случае не уходит |
403 | Бюджет ключа исчерпан или модель не разрешена для ключа | Дождитесь авто-сброса бюджета, увеличьте бюджет или поправьте список моделей в настройках ключа |
429 | Превышен rate limit | Повторяйте запрос с экспоненциальной задержкой (backoff) |
Ошибки провайдера
Если ошибку вернул сам провайдер (4xx/5xx апстрима), шлюз пробрасывает её
ответ как есть, а зарезервированные средства возвращает на баланс полностью.
При 502, 503, 504 и сетевых ошибках шлюз сам выполняет повторные попытки.
Код 429 от провайдера пробрасывается клиенту без повтора — повторять
запрос должен клиент.
Ограничения частоты запросов
- 60 запросов в минуту на API-ключ. При превышении —
429. - 20 запросов в минуту с одного IP для обращений без ключа.
Окно скользящее, длиной 60 секунд. В ответе с кодом 429 приходят заголовки
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset и
Retry-After — ориентируйтесь на них.
Рекомендации по повторам
429— повтор с экспоненциальной задержкой и джиттером (1s, 2s, 4s, …).5xxпровайдера — безопасно повторять: деньги за неотработанный запрос не списываются.400— не повторять: исправьте запрос (неизвестная модель, пустойmessagesи т.п.).401/402/403— повтор бессмысленен до устранения причины.
Диагностика
GET /v1/balance— проверить баланс аккаунта;GET /v1/key— проверить остаток бюджета и срок действия ключа;- поле
codeв теле ошибки — машиночитаемая причина (insufficient_funds,budget_exceeded,model_not_allowedи т.д.).