docs/errors

Каждая ошибка — и что с ней делать

Ответ всегда в формате OpenAI: HTTP-статус и JSON с полями type, code и message. По code можно ветвить логику — он не меняется, message написан для людей. В каждом ответе есть заголовок X-Request-ID: назовите его поддержке, и мы найдём запрос.

Пример ответа

HTTP/1.1 402 Payment Required
X-Request-ID: <id запроса>

{
  "error": {
    "type": "insufficient_funds",
    "code": "insufficient_funds",
    "message": "Недостаточно средств на балансе…"
  }
}

Запрос и ключ

Статус	code	Когда	Что делать	Повтор
400	invalid_request_error	Модель отклонила параметр или тело запроса не удалось разобрать (422 — с полем param).	Прочитайте message — в нём причина. Исправьте параметр.	исправить запрос
401	authentication_error	Ключ не передан, удалён или в неверном формате.	Скопируйте ключ заново в кабинете или боте. Формат: sk-ag-…	исправить запрос
403	permission_error	У ключа или аккаунта нет доступа к этому действию.	Проверьте ключ в кабинете; если не помогает — напишите в поддержку.	исправить запрос
404	model_not_found	Такой модели нет в каталоге.	Возьмите id из GET /v1/models или из прайса.	исправить запрос
409	idempotency_conflict	Повтор с тем же Idempotency-Key, но другим телом запроса.	Для нового запроса используйте новый ключ идемпотентности.	исправить запрос

Баланс и лимиты

Статус	code	Когда	Что делать	Повтор
402	insufficient_funds	На балансе недостаточно средств для запроса.	Пополните баланс картой РФ, через СБП или криптой.	исправить запрос
429	rate_limit_exceeded	Превышен лимит запросов в минуту на ключ (или провайдер временно ограничил запросы).	Подождите retry-after секунд или распределите нагрузку на несколько ключей.	можно повторить
429	monthly_token_limit_exceeded	Сработал месячный лимит токенов, заданный ключу.	Поднимите лимит ключа в кабинете или дождитесь нового месяца.	исправить запрос

Провайдеры и платформа

Статус	code	Когда	Что делать	Повтор
404	model_temporarily_unavailable	Все провайдеры модели сейчас её не отдают — мы временно скрыли её из каталога.	Выберите другую модель. Вернём автоматически, когда провайдер восстановится.	исправить запрос
502	upstream_error	Провайдер вернул ошибку, резервных маршрутов не осталось.	Повторите запрос с паузой.	можно повторить
503	service_unavailable	Провайдер модели временно недоступен.	Повторите позже или смените модель.	можно повторить
503	maintenance	На платформе идут технические работы.	Сообщение и ориентировочное время — в ответе и на сайте.	можно повторить
504	timeout	Провайдер не ответил вовремя.	Повторите запрос; для длинных ответов включите stream.	можно повторить
500	server_error	Внутренняя ошибка AggreGate.	Повторите; если повторяется — напишите в поддержку с X-Request-ID.	можно повторить

Ошибки провайдера (5xx, таймауты) до начала ответа мы сначала обходим через резервный канал — клиент получает ошибку, только если все маршруты недоступны. Подключение инструментов — в разделе «Подключение».