Частые ошибки

Формат тела ошибки

Эндпоинты моделей возвращают ошибки в формате JSON:

{
  "error": {
    "message": "Insufficient user quota, remaining: ＄0.000000 (request id: 202610230158421013999388268d9d615)",
    "type": "error",
    "code": "insufficient_user_quota"
  }
}

message — понятное человеку описание, в конце которого стоит (request id: <id>). Тот же id возвращается в заголовке ответа X-Oneapi-Request-Id; прилагайте его при обращении в поддержку.
code — машиночитаемый код ошибки. У некоторых ошибок он равен пустой строке; в этом случае ориентируйтесь на HTTP-статус.
message локализуется по языку пользователя или Accept-Language и может меняться, поэтому в логике программы опирайтесь на HTTP-статус и code.

Claude Messages (/v1/messages) вместо этого возвращает {"type": "error", "error": {"type": "...", "message": "..."}}. Эндпоинты асинхронных задач (/v1/video/generations, /v1/videos, /suno/*) возвращают ошибки, возникшие после маршрутизации, в виде {"code", "message", "data"}, причём в message нет request id.

401 Unauthorized

API-ключ отсутствует, недействителен, истёк, отключён или исчерпал квоту:

Заголовок Authorization отсутствует или не в формате Bearer sk-....
Ключ удалён, отключён или истёк.
Оставшаяся квота ключа исчерпана.
На эндпоинт модели отправлен Management Key (rat_...); для вызова моделей нужен API-ключ sk-.

При необходимости создайте новый ключ на странице API Keys. Квота и срок действия ключа описаны в разделе Баланс и квоты.

403 Forbidden

У 403 две совершенно разные причины; сначала посмотрите code в ответе.

Недостаточно баланса или квоты ключа

insufficient_user_quota: баланса аккаунта не хватает на расчётную стоимость запроса, либо в подписке не осталось квоты.
pre_consume_token_quota_failed: оставшейся квоты ключа не хватает на расчётную стоимость запроса.

Пополните баланс, увеличьте квоту ключа или уменьшите max_tokens, чтобы расчётная стоимость уложилась в квоту. Подробнее в разделе Баланс и квоты.

Нет прав

У таких ошибок code обычно пустой; по сообщению видно, какая проверка не прошла:

Ограничения моделей ключа не включают эту модель (This token has no access to model ...).
Группа ключа недоступна вашему аккаунту.
Исходный IP отсутствует в списке разрешённых IP ключа (code access_denied).
Аккаунт отключён.

429 Too Many Requests

Превышен лимит частоты запросов. Лимиты считаются на аккаунт: все ключи одного аккаунта делят квоту, поэтому добавление ключей не повышает лимит. Отклонённые запросы не тарифицируются.

Повторяйте с экспоненциальной задержкой и случайным джиттером.
Снизьте параллелизм или распределите запросы по времени.
Ответ 429 может иметь пустое тело; ориентируйтесь на код статуса, а не на сообщение.

Как работают лимиты запросов к моделям и как повторяются ответы 429 от вышестоящих сервисов, см. в разделе Использование и биллинг.

503 Модель недоступна

code model_not_found с сообщением вида “No valid upstream service”: сейчас нет канала, обслуживающего эту модель для вашей группы. Проверьте написание ID модели и доступность модели вашему аккаунту; немедленный повтор того же запроса обычно не помогает.

502 / 503 Ошибка вышестоящего сервиса

Ответ 502 или другой 5xx от поставщика модели передаётся как есть, если все повторы не удались.
code get_channel_failed с сообщением “Upstream service is temporarily unavailable”: аккаунт вышестоящего сервиса за каналом непригоден (например, не хватает баланса или недействительны учётные данные). RouteAPI по возможности повторяет запрос через другой канал, при неудаче возвращает это общее сообщение, поднимает внутренний алерт и может отключить неисправный канал; повторите позже.
code client_failfast (503): один и тот же API-ключ слишком часто получает ошибки для этой модели, поэтому для пары ключ/модель включено короткое окно защиты. Ответ содержит Retry-After и X-Client-Failfast: 1; подождите перед повтором и сначала устраните причину ошибки.

Временные ошибки — повторите позже. Если они не проходят, обратитесь в поддержку с request id.