Ошибки и повторы
У каждой ошибки одна форма и постоянный код. Решайте по коду, что делать, и повторяйте только то, что может пройти.
Тело ошибки
Каждая ошибка эндпоинтов /v1, включая совместимые с OpenAI, приходит в этом теле. Это объект ошибки OpenAI с добавленным идентификатором запроса, поэтому OpenAI SDK читают его как обычно.
| Поле | Значение |
|---|---|
error.type | Семейство ошибки, которое задаёт HTTP-статус. Типы перечислены ниже. |
error.code | Постоянный код для программ. Решайте, что делать, по этому полю. |
error.message | Описание ошибки для людей. Оно может меняться, поэтому никогда не опирайтесь на него. |
error.param | Первый неверный параметр или null. |
error.fields | Только при ошибках валидации: каждое неверное поле и его первое сообщение. |
request_id | Идентификатор этого запроса, такой же, как в заголовке X-Request-Id. |
Если поток чата обрывается после начала, он отправляет последнее событие с этим телом, а затем [DONE]. Статус к этому моменту уже 200, поэтому читайте событие.
Типы ошибок
Тип зависит от статуса. Это те же четыре типа, что у OpenAI.
| Статус | Тип |
|---|---|
402 | insufficient_quota |
429 | rate_limit_error |
5xx | server_error |
| Любой другой 4xx | invalid_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_request400, 422invalid_request_error | Запрос составлен неверно или не прошёл валидацию. |
invalid_api_key401invalid_request_error | API ключ отсутствует или не распознан. |
api_key_disabled401invalid_request_error | API ключ отключён, его можно включить снова. |
api_key_revoked401invalid_request_error | API ключ отозван и больше никогда не может использоваться. |
api_key_expired401invalid_request_error | Срок действия API ключа истёк. |
insufficient_balance402insufficient_quota | Баланса организации недостаточно для этого запроса. |
spend_limit_exceeded402insufficient_quota | Запрос превысил бы месячный лимит расходов API ключа. |
insufficient_permissions403invalid_request_error | У API ключа нет права, которое нужно для этого запроса. |
ip_not_allowed403invalid_request_error | IP-адреса запроса нет в списке разрешённых адресов API ключа. |
no_organization403invalid_request_error | API ключ принадлежит пользователю без организации. |
voice_unavailable403invalid_request_error | Этот voice_id недоступен для данного аккаунта. |
forbidden403invalid_request_error | Этому API ключу не разрешено выполнять этот запрос. |
not_found404invalid_request_error | Маршрут или ресурс не существует в этой организации. |
model_not_found404invalid_request_error | Запрошенная модель не существует или недоступна. |
method_not_allowed405invalid_request_error | Этот HTTP-метод не поддерживается на данном маршруте. |
conflict409invalid_request_error | Запрос противоречит текущему состоянию ресурса. |
idempotency_conflict409invalid_request_error | Idempotency-Key уже использован с другим запросом. |
job_not_finished409invalid_request_error | TTS-задача ещё не завершена. |
job_failed409invalid_request_error | TTS-задача завершилась ошибкой, аудио нет. |
gone410invalid_request_error | Ресурс больше недоступен. |
audio_expired410invalid_request_error | Срок хранения аудио TTS-задачи истёк. |
audio_too_large413invalid_request_error | Аудио слишком большое, чтобы отправить его как ресурс MCP; скачайте его по ссылке. |
input_too_large413, 422invalid_request_error | Входные данные превышают допустимый размер. |
unsupported_media_type415invalid_request_error | Тип загруженного файла не поддерживается. |
batch_too_large422invalid_request_error | В пакете слишком много входов для эмбеддингов. |
too_many_documents422invalid_request_error | В запросе слишком много документов для реранжирования. |
context_length_exceeded422invalid_request_error | Промпт вместе с max_tokens превышает длину контекста модели. |
upstream_rejected_input422invalid_request_error | Сервер модели отклонил входные данные; повтор без изменений не поможет. |
rate_limit_exceeded429rate_limit_error | Превышен лимит запросов в минуту для API ключа или его организации. |
concurrency_limit_exceeded429rate_limit_error | Для этого API ключа или его организации одновременно выполняется слишком много запросов. |
upstream_rate_limited429rate_limit_error | Сервер модели перегружен; повторите чуть позже. |
too_many_active_jobs429rate_limit_error | У этого API ключа или его организации слишком много TTS-задач в очереди или в работе. |
server_error500server_error | Произошла непредвиденная ошибка. |
synthesis_failed500server_error | Не удалось синтезировать речь или диалог; повторите чуть позже. |
transcription_failed500server_error | Не удалось распознать речь; повторите чуть позже. |
upstream_error502server_error | Сбой в сервисе модели или голоса; повторите чуть позже. |
service_unavailable503server_error | Необходимый сервис временно недоступен. |
storage_failed503server_error | Аудио создано, но его не удалось сохранить для идемпотентного повтора. |
Задача, которая завершилась неудачей, не возвращает ошибку. Она переходит в статус failed и содержит свой error.code, перечисленный вместе с задачей в справочнике по синтезу речи.