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