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

Ошибки и повторы

У каждой ошибки одна форма и постоянный код. Решайте по коду, что делать, и повторяйте только то, что может пройти.

Тело ошибки

Каждая ошибка эндпоинтов /v1, включая совместимые с OpenAI, приходит в этом теле. Это объект ошибки OpenAI с добавленным идентификатором запроса, поэтому OpenAI SDK читают его как обычно.

JSON
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "The text field is required.",
    "param": "text",
    "fields": {
      "text": "The text field is required."
    }
  },
  "request_id": "0b8e8a5e-6f5c-4f7e-9d63-2c1f0f4b7a51"
}

ПолеЗначение
error.typeСемейство ошибки, которое задаёт HTTP-статус. Типы перечислены ниже.
error.codeПостоянный код для программ. Решайте, что делать, по этому полю.
error.messageОписание ошибки для людей. Оно может меняться, поэтому никогда не опирайтесь на него.
error.paramПервый неверный параметр или null.
error.fieldsТолько при ошибках валидации: каждое неверное поле и его первое сообщение.
request_idИдентификатор этого запроса, такой же, как в заголовке X-Request-Id.

Если поток чата обрывается после начала, он отправляет последнее событие с этим телом, а затем [DONE]. Статус к этому моменту уже 200, поэтому читайте событие.

Типы ошибок

Тип зависит от статуса. Это те же четыре типа, что у OpenAI.

СтатусТип
402insufficient_quota
429rate_limit_error
5xxserver_error
Любой другой 4xxinvalid_request_error

Идентификаторы запросов

Каждый ответ, включая аудио и ошибки, содержит заголовок X-Request-Id. Каждое тело ошибки и каждое тело с data повторяет его в request_id; успешные ответы эндпоинтов, совместимых с OpenAI и Cohere, сохраняют свою форму, поэтому там читайте заголовок. Указывайте его, когда пишете в поддержку: по нему мы находим запрос в наших журналах.

Мы создаём новый идентификатор для каждого запроса и не учитываем X-Request-Id, присланный вами. Повторённый ответ тоже получает новый идентификатор.

Когда повторять запрос

Решайте по статусу и коду. Повтор, который не может пройти, только расходует лимит запросов.

ОтветЧто делать
429
Подождите столько секунд, сколько указано в Retry-After, и отправьте тот же запрос снова.
500502503
Повторяйте с растущей паузой: 1 секунда, затем 2, затем 4, и остановитесь после нескольких попыток. Если POST принимает Idempotency-Key (см. ниже), повторяйте его с тем же ключом, чтобы он не оплачивался дважды.
409 job_not_finished
Задача ещё в очереди или выполняется. Проверьте её снова через несколько секунд.
409 idempotency_conflict
Ключ уже использован с другим телом. Отправьте новый запрос с новым Idempotency-Key.
409 job_failed410 audio_expired
Аудио уже не появится. Создайте новую задачу.
413 input_too_large422 input_too_large
Сократите входные данные или разделите их и отправьте снова.
400401402403404405409 conflict422
Никогда не повторяйте такие запросы без изменений. Сначала исправьте запрос, ключ, его права, его лимиты или баланс.

Безопасный повтор POST

Передавайте заголовок Idempotency-Key длиной до 191 символа в POST-запросах ниже. Повтор с тем же ключом получает исходный результат с Idempotency-Replayed: 1, а работа не выполняется и не оплачивается повторно: то же аудио или та же расшифровка, задача в её текущем состоянии или голос в его текущем виде. Если голос, созданный с таким ключом, с тех пор удалён, повтор создаёт новый голос. Ключи принадлежат вашей организации.

ЭндпоинтСколько хранится ключ
POST /api/v1/tts/synthesizePOST /api/v1/tts/dialogue
7 дней
POST /api/v1/tts/jobs
До удаления задачи, по умолчанию через сутки после её завершения
POST /api/v1/stt/transcribePOST /api/v1/tts/voices
Всегда. Используйте ключ повторно только для того же запроса.

Тот же ключ с другим телом получает ответ 409 idempotency_conflict, а ключ длиннее 191 символа — 400 invalid_request.

Коды ошибок

Все коды, которыми API может ответить на ваши запросы, и статусы, с которыми они приходят. Могут появиться новые коды, поэтому незнакомый код обрабатывайте по его статусу.

КодЗначение
invalid_request

400, 422invalid_request_error

Запрос составлен неверно или не прошёл валидацию.
invalid_api_key

401invalid_request_error

API ключ отсутствует или не распознан.
api_key_disabled

401invalid_request_error

API ключ отключён, его можно включить снова.
api_key_revoked

401invalid_request_error

API ключ отозван и больше никогда не может использоваться.
api_key_expired

401invalid_request_error

Срок действия API ключа истёк.
insufficient_balance

402insufficient_quota

Баланса организации недостаточно для этого запроса.
spend_limit_exceeded

402insufficient_quota

Запрос превысил бы месячный лимит расходов API ключа.
insufficient_permissions

403invalid_request_error

У API ключа нет права, которое нужно для этого запроса.
ip_not_allowed

403invalid_request_error

IP-адреса запроса нет в списке разрешённых адресов API ключа.
no_organization

403invalid_request_error

API ключ принадлежит пользователю без организации.
voice_unavailable

403invalid_request_error

Этот voice_id недоступен для данного аккаунта.
forbidden

403invalid_request_error

Этому API ключу не разрешено выполнять этот запрос.
not_found

404invalid_request_error

Маршрут или ресурс не существует в этой организации.
model_not_found

404invalid_request_error

Запрошенная модель не существует или недоступна.
method_not_allowed

405invalid_request_error

Этот HTTP-метод не поддерживается на данном маршруте.
conflict

409invalid_request_error

Запрос противоречит текущему состоянию ресурса.
idempotency_conflict

409invalid_request_error

Idempotency-Key уже использован с другим запросом.
job_not_finished

409invalid_request_error

TTS-задача ещё не завершена.
job_failed

409invalid_request_error

TTS-задача завершилась ошибкой, аудио нет.
gone

410invalid_request_error

Ресурс больше недоступен.
audio_expired

410invalid_request_error

Срок хранения аудио TTS-задачи истёк.
audio_too_large

413invalid_request_error

Аудио слишком большое, чтобы отправить его как ресурс MCP; скачайте его по ссылке.
input_too_large

413, 422invalid_request_error

Входные данные превышают допустимый размер.
unsupported_media_type

415invalid_request_error

Тип загруженного файла не поддерживается.
batch_too_large

422invalid_request_error

В пакете слишком много входов для эмбеддингов.
too_many_documents

422invalid_request_error

В запросе слишком много документов для реранжирования.
context_length_exceeded

422invalid_request_error

Промпт вместе с max_tokens превышает длину контекста модели.
upstream_rejected_input

422invalid_request_error

Сервер модели отклонил входные данные; повтор без изменений не поможет.
rate_limit_exceeded

429rate_limit_error

Превышен лимит запросов в минуту для API ключа или его организации.
concurrency_limit_exceeded

429rate_limit_error

Для этого API ключа или его организации одновременно выполняется слишком много запросов.
upstream_rate_limited

429rate_limit_error

Сервер модели перегружен; повторите чуть позже.
too_many_active_jobs

429rate_limit_error

У этого API ключа или его организации слишком много TTS-задач в очереди или в работе.
server_error

500server_error

Произошла непредвиденная ошибка.
synthesis_failed

500server_error

Не удалось синтезировать речь или диалог; повторите чуть позже.
transcription_failed

500server_error

Не удалось распознать речь; повторите чуть позже.
upstream_error

502server_error

Сбой в сервисе модели или голоса; повторите чуть позже.
service_unavailable

503server_error

Необходимый сервис временно недоступен.
storage_failed

503server_error

Аудио создано, но его не удалось сохранить для идемпотентного повтора.

Задача, которая завершилась неудачей, не возвращает ошибку. Она переходит в статус failed и содержит свой error.code, перечисленный вместе с задачей в справочнике по синтезу речи.