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