Обработка ошибок

Все ошибки возвращаются в OpenAI-совместимом формате:

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

Коды

HTTP	type	Когда возникает
400	invalid_request_error	Неверные параметры, неподдерживаемая модель
401	authentication_error	Нет/неверный ключ
402	insufficient_balance	На балансе аккаунта < 0 ₽
403	model_not_allowed	Модель не разрешена для этого ключа
404	model_not_found	Модели нет в каталоге
409	idempotency_conflict	Повторный платёж с тем же Idempotency-Key
413	payload_too_large	Запрос > 10 MB
422	unprocessable_entity	Валидация payload не прошла
429	rate_limit_exceeded	Превышен RPM/TPM ключа или upstream
500	internal_server_error	Внутренняя ошибка шлюза
502	upstream_error	OpenRouter/провайдер вернул ошибку и фоллбэк не помог
503	service_unavailable	LiteLLM/Postgres/Redis недоступны
504	upstream_timeout	Провайдер не ответил в течение timeout

Что делать

• 401 / 402 — проверить ключ и баланс в кабинете. Пополнить, чтобы автоматически разблокировать ключи.
• 429 — подождать Retry-After секунд, добавить экспоненциальный backoff.
• 502 / 504 — повторить запрос (шлюз уже сделал num_retries: 3, но бывают долгие провайдерские штормы).
• 5xx подряд — пишите в поддержку с x-llmgw-request-id из заголовков.

Идемпотентность

Для запросов на оплату передавайте Idempotency-Key (UUID), чтобы повтор не списал деньги дважды.

Журнал ошибок

Каждая ошибка логируется с request_id, который виден в заголовках ответа (x-llmgw-request-id). Это id хранится 30 дней — указывайте его в обращениях.