Перейти до вмісту

Помилки та повторні спроби

Помилки бізнес-логіки повертають 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, слід обробляти з використанням експоненціального зменшення періоду очікування.

Стратегія повторної спроби

Section titled “Стратегія повторної спроби”
  • Запити можна повторно надсилати безпосередньо.
  • Під час повторної спроби виконання запиту на створення використовуйте той самий 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())