Перейти к содержимому

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

Ошибки бизнес-логики возвращают code и message на верхнем уровне тела ответа. detail обычно совпадает с message, но может быть другим, более коротким описанием (как ниже); пользователям следует отображать message. Сообщения на китайском языке:

{
"code": "CONCURRENCY_LIMITED",
"message": "排队中的文件已达上限(1000 个),请等部分文件翻译完成后再提交",
"detail": "排队文件完成一部分后可继续提交"
}

Некоторые бизнес-ошибки возвращают только code. Ошибки валидации возвращают 422 со списком ошибок полей в detail:

{
"detail": [
{ "loc": ["body", "target_lang"], "msg": "Field required", "type": "missing" }
]
}

Обрабатывайте ошибки сначала по статусу HTTP, затем по code: многие ошибки возвращают только универсальный UNKNOWN_ERROR, и лишь некоторые содержат конкретный code (например, 429 случаев ниже). Запишите заголовок ответа X-Request-Id для устранения неполадок.

СтатусЗначениеСовет
400Недопустимый запрос, например, выбранный параметр недоступен.Исправьте запрос; не повторяйте попытку
401Отсутствует, недействительно, истекло или аннулировано удостоверениеИзменить учетные данные
402Остаток (за вычетом задолженности) не превышает пороговое значение для задачи или является отрицательным; при наличии API‑ключа оставшийся бюджет ключа может быть слишком низким.Пополните (или увеличьте бюджет ключа), затем отправьте запрос повторно.
403Пределы ключа не позволяют выполнить эту операцию (например, настройка перевода недопустима), учетная запись отключена или операция должна выполняться в браузере с авторизацией (например, управление API‑ключами).Проверьте основные настройки или воспользуйтесь веб-сайтом
404Ресурс не существует, был удалён или принадлежит другой учётной записи (все три варианта выглядят одинаково)Проверьте идентификатор
409Ключ идемпотентности использовался для другого запроса, либо состояние ресурса не позволяет выполнить операцию.Запросите исходную операцию, затем примите решение.
410Ресурс или конечная точка утрачены навсегда; например, это может быть недоступная более конечная точка или удалённое задание, связанное с ключом идемпотентности.Не повторять попытку
413Файл или тело запроса превышает лимитИспользуйте файл меньшего размера
415Неподдерживаемый формат файлаИспользуйте другой формат
422Проверка не пройдена, либо файл пуст или в нём нет данных для обработки.Исправьте поля; не выполняйте автоматическую повторную попытку
429Ограничено скоростью, размером очереди или бюджетомСм. ниже
5xxВременная ошибка службыЭкспоненциальное увеличение задержки с максимальным числом попыток
codeЗначениеЧто делать
RATE_LIMITEDСлишком много запросовПодождите Retry-After, затем повторите попытку
CONCURRENCY_LIMITEDСлишком много заданий по переводу файлов находится в очередиПодождите Retry-After или завершения некоторых заданий
AUTH_API_KEY_QUOTA_EXCEEDEDБюджет ключа исчерпанНе повторяйте попытку, пока бюджет не будет увеличен.

A 429, не имеющий Retry-After, следует обрабатывать с использованием экспоненциального退避.

  • Запросы можно повторно отправлять напрямую.
  • При повторной попытке выполнения запроса на создание используйте тот же Idempotency-Key и точно такой же тело запроса; для каждого нового отправления задавайте новый ключ.
  • После неудачной загрузки запросите новый адрес для загрузки.
  • Устанавливайте временные лимиты подключения, чтения и общей задержки для каждого запроса, добавляйте случайное джиттер при повторных попытках и ограничивайте максимальное число попыток.
import random
import time
for attempt in range(5):
response = call_api()
if response.status_code not in {429, 500, 502, 503, 504}:
break
if response.status_code == 429 and response.json().get("code") == "AUTH_API_KEY_QUOTA_EXCEEDED":
break
retry_after = response.headers.get("Retry-After")
delay = float(retry_after) if retry_after else min(2 ** attempt, 16)
time.sleep(delay + random.random())