Помилки та повторні спроби
Помилки бізнес-логіки повертають 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
Section titled “Статус HTTP”| Статус | Значення | Поради |
|---|---|---|
400 | Недійсний запит, наприклад, обраний параметр недоступний. | Виправте запит; не повторюйте спробу |
401 | Відсутні, недійсні, прострочені або скасовані облікові дані | Змінити облікові дані |
402 | Сальдо (після вирахування боргів) не перевищує порогового значення для завдання або є від’ємним; у разі наявності API-ключу залишок бюджету ключа може бути занадто низьким. | Поповніть (або збільште бюджет ключа), а потім надішліть запит ще раз. |
403 | Межі ключа не дозволяють виконати цю операцію (наприклад, налаштування перекладу заборонено), обліковий запис вимкнено або операцію потрібно виконувати у підключенному браузері (наприклад, керування API-ключами). | Перевірте ключові налаштування або скористайтеся вебсайтом |
404 | Ресурс не існує, був видалений або належить іншому обліковому запису (усе це виглядає однаково) | Перевірте ідентифікатор |
409 | Ключ ідемпотентності було використано для іншого запиту, або стан ресурсу не дозволяє виконати операцію. | Запитайте вихідну операцію, а потім прийміть рішення |
410 | Ресурс або кінцева точка остаточно відсутні, наприклад, застаріла кінцева точка або видалене завдання, пов’язане з ключем ідемпотентності. | Не повторювати спробу |
413 | Файл або тіло запиту перевищує ліміт | Використайте менший файл |
415 | Непідтримуваний формат файлу | Використайте інший формат |
422 | Підтвердження не пройдено, або файл порожній або в ньому немає даних для обробки. | Виправте поля; не повторюйте спробу автоматично |
429 | Швидкість, розмір черги або бюджет обмежені | Див. нижче |
5xx | Тимчасова помилка служби | Експоненціальне зменшення періоду очікування з обмеженням на максимальну кількість спроб |
Обробка 429
Section titled “Обробка 429”code | Значення | Що робити |
|---|---|---|
RATE_LIMITED | Забагато запитів | Зачекайте на Retry-After, потім повторіть спробу |
CONCURRENCY_LIMITED | Занадто багато завдань перекладу файлів знаходяться в черзі | Зачекайте на Retry-After або на завершення деяких завдань |
AUTH_API_KEY_QUOTA_EXCEEDED | Бюджет ключа вичерпано | Не повторюйте спробу, поки бюджет не буде збільшено. |
A 429, що не має Retry-After, слід обробляти з використанням експоненціального зменшення періоду очікування.
Стратегія повторної спроби
Section titled “Стратегія повторної спроби”- Запити можна повторно надсилати безпосередньо.
- Під час повторної спроби виконання запиту на створення використовуйте той самий
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())