Перейти к содержанию

Ошибки и поддержка

Как выглядит ошибка

Если Nexus отклоняет запрос, ответ содержит:

  • message
  • type
  • code
  • param иногда, если ошибка относится к конкретному полю
  • request_id

Для поддержки важнее всего request_id.

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

invalid_key

Ключ не передан, указан неверно, отключен или отозван.

Проверьте:

  • заголовок Authorization: Bearer <API_KEY>;
  • заголовок x-api-key, если ваш клиент использует его;
  • отсутствие лишних пробелов.

endpoint_not_allowed

Ваш ключ не имеет доступа к выбранному маршруту.

Проверьте, что клиент настроен под нужный сценарий. Если нужен другой доступ, обратитесь в поддержку.

model_not_allowed

Модель не включена для вашего ключа.

Выполните GET /v1/models и выберите модель из ответа.

unsupported_model

Модель не работает на выбранном маршруте.

Например, одна модель может быть доступна для chat.completions, но не для responses.

unsupported_endpoint

Клиент отправил запрос на неподдерживаемый маршрут.

Используйте только маршруты из страницы Поддерживаемые маршруты

streaming_not_supported

Клиент запросил streaming там, где Nexus его не поддерживает.

Streaming поддерживается для:

  • POST /v1/chat/completions;
  • POST /v1/messages;
  • POST /v1/responses;
  • POST /v1/responses/compact;
  • POST /v1beta/models/{model}:streamGenerateContent.

missing_model

В теле запроса нет поля model.

Добавьте модель в JSON-запрос.

invalid_request_json

Nexus не смог разобрать JSON body.

Проверьте синтаксис JSON. Если в ответе есть param: "body", проблема именно в теле запроса.

unsupported_content_type

Для этого маршрута передан неверный Content-Type.

JSON-маршруты требуют application/json. Multipart-маршруты требуют multipart/form-data.

payload_too_large

Размер запроса превышает допустимый лимит маршрута.

Уменьшите размер body, файла или base64-вложения и повторите запрос.

insufficient_balance

Текущий баланс профиля Nexus ниже порога допуска нового запроса.

Пополните баланс и повторите запрос.

pricing_unavailable

Для выбранной модели временно недоступен безопасный расчет стоимости.

Обычно это решается на стороне поддержки. Повторите позже или напишите в поддержку с request_id.

duplicate_request_id

Такой x-request-id уже был принят ранее для другого запроса.

Заголовок x-request-id предназначен для сквозной трассировки уникальной попытки. Создайте новый x-request-id для нового запроса. Для безопасных повторов при сетевых сбоях и таймаутах используйте заголовок Idempotency-Key (подробнее — в разделе Повторы и идемпотентность).

invalid_idempotency_key

Заголовок Idempotency-Key имеет недопустимый формат.

Ключ должен содержать от 1 до 256 печатных ASCII-символов. Используйте стандартный формат (например, UUID v4).

idempotency_in_progress

Запрос с переданным Idempotency-Key в данный момент уже обрабатывается системой.

Подождите указанное в заголовке Retry-After количество секунд (обычно 1 секунда) и повторите запрос с тем же ключом и телом.

idempotency_conflict

Заголовок Idempotency-Key уже был использован с другим телом запроса.

Один и тот же ключ идемпотентности нельзя использовать для разных запросов (например, при изменении модели, текста или параметров). Для нового запроса сгенерируйте новый ключ.

result_expired

Срок хранения сохранённого результата для данного Idempotency-Key истёк (прошло более 24 часов).

Результат удалён из кэша. Сгенерируйте новый Idempotency-Key для выполнения нового запроса.

Превышение лимитов параллелизма или частоты запросов (429)

Ошибки customer_concurrency_exceeded, customer_rate_limit_exceeded, key_concurrency_exceeded, key_rate_limit_exceeded возвращаются при превышении настроенных ограничений на число одновременных запросов или частоту обращений.

Ответ содержит заголовок Retry-After. Подождите указанное количество секунд и уменьшите параллелизм запросов.

Ограничения вычислительных мощностей и защита сервиса (503)

Ошибки provider_capacity_exceeded, global_capacity_exceeded, queue_full, queue_timeout, start_capacity_exceeded, sse_capacity_exceeded, ws_capacity_exceeded, drain_capacity_exceeded, protection_mode_engaged, billing_protection_engaged, server_shutting_down возвращаются, когда вычислительные ресурсы временно перегружены или сервис находится в режиме защиты/перезагрузки. start_capacity_exceeded значит, что сервис не смог начать обработку за отведённое время: это не внутренний сбой, запрос можно повторить.

Nexus возвращает HTTP 503 Service Unavailable с заголовком Retry-After. Повторите запрос через указанное время, используя тот же Idempotency-Key.

billing_finalization_failed

Запрос дошел до этапа финального учета, но автоматическое завершение не удалось.

Передайте request_id в поддержку. Повторять запрос сразу не стоит, пока не понятно, был ли ответ учтен.

Ошибка внешнего запроса

Внешний запрос не был успешно завершен.

Повторите позже. Если ошибка повторяется, передайте в поддержку модель, маршрут, время ошибки и request_id.

upstream_unavailable

Nexus не может безопасно начать внешний запрос, потому что маршрут временно недоступен.

Обычно это требует проверки на стороне сервиса. Повторите позже или напишите в поддержку с request_id.

upstream_timeout

Внешний запрос не получил ответ за допустимое время.

Такой запрос обычно можно повторить позже. Если таймауты повторяются, передайте в поддержку request_id.

internal_error

Внутренняя ошибка сервиса.

Передайте request_id в поддержку.

Когда писать в поддержку

Пишите, если:

  • ключ активен, но модели не отображаются;
  • баланс пополнен, но запросы отклоняются;
  • одна и та же ошибка повторяется;
  • нужна помощь с профилем, ключом или переносом баланса;
  • нужна индивидуальная проверка списания.

Контакт:

Что приложить

  • request_id;
  • модель;
  • маршрут;
  • примерное время ошибки;
  • название клиента или инструмента.