Przejdź do głównej zawartości

Błędy i powtórne próby

Błędy biznesowe zwracają code i message na najwyższym poziomie ciała odpowiedzi. detail jest zwykle identyczny z message, ale może stanowić krótsze, odmienne wyjaśnienie (jak poniżej); użytkownikom wyświetlany jest message. Wiadomości są w języku chińskim:

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

Niektóre błędy biznesowe zwracają wyłącznie code. Błędy walidacji zwracają 422 wraz z listą błędów pól w detail:

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

Najpierw obsłuż błędy o statusie HTTP, a następnie o statusie code: wiele błędów zwraca jedynie uniwersalny kod UNKNOWN_ERROR, a tylko niektóre zawierają konkretny kod code (np. 429 przypadków wymienionych poniżej). Zapisz nagłówek odpowiedzi X-Request-Id w celu rozwiązywania problemów.

StatusZnaczeniePorady
400Nieprawidłowe żądanie, na przykład wybrane ustawienie jest niedostępnePopraw żądanie; nie ponawiaj próby
401Brak, nieprawidłowe, wygasłe lub unieważnione poświadczeniaZmień poświadczenia
402Saldo (po odjęciu długu) nie przekracza progu zadania lub jest ujemne; w przypadku klucza API pozostały budżet klucza może być zbyt niski.Włóż więcej środków (lub zwiększ budżet klucza), a następnie prześlij ponownie.
403Ograniczenia klucza nie pozwalają na tę operację (np. ustawienie tłumaczenia jest niedozwolone), konto jest wyłączone lub operacja musi być wykonywana w przeglądarce z zalogowanym kontem (na przykład zarządzanie kluczami API).Sprawdź kluczowe ustawienia lub skorzystaj z witryny internetowej
404Zasób nie istnieje, został usunięty lub należy do innego konta (wszystkie trzy przypadki wyglądają identycznie)Sprawdź identyfikator
409Klucz idempotencji został użyty w innym żądaniu, lub stan zasobu nie pozwala na wykonanie tej operacji.Zapytaj o oryginalną operację, a następnie podejmij decyzję.
410Zasób lub punkt końcowy został trwale usunięty, na przykład wycofany punkt końcowy lub usunięte zadanie powiązane z kluczem idempotencji.Nie ponawiaj próby
413Plik lub treści żądania przekraczają limitUżyj mniejszego pliku
415Nieobsługiwany format plikuUżyj innego formatu
422Walidacja nie powiodła się, lub plik jest pusty lub nie zawiera żadnych danych do przetworzenia.Popraw pola; nie ponawiaj automatycznie próby
429Ograniczenie stawki, rozmiaru kolejki lub budżetuZobacz poniżej
5xxTemporary service errorEksponencjalne wydłużanie czasu oczekiwania z maksymalną liczbą prób
codeZnaczenieCo zrobić
RATE_LIMITEDZbyt wiele żądańPoczekaj na Retry-After, a następnie spróbuj ponownie
CONCURRENCY_LIMITEDZbyt wiele zadań tłumaczenia plików jest w kolejce.Poczekaj na Retry-After lub na zakończenie niektórych zadań.
AUTH_API_KEY_QUOTA_EXCEEDEDBudżet klucza został wyczerpany.Nie ponawiaj próby, dopóki budżet nie zostanie zwiększony.

A 429 bez Retry-After powinien być obsługiwany przy użyciu eksponencjalnego wycofania.

  • Zapytania mogą być ponownie próbowane bezpośrednio.
  • Podczas ponownego próbowania przesłania żądania utworzenia, użyj ponownie ten sam identyfikator Idempotency-Key i dokładnie tę samą treść; dla każdego nowego przesyłania użyj nowego klucza.
  • Po nieudanym przesyłaniu poproś o nowy adres do przesyłania.
  • Ustaw limity czasu połączenia, odczytu i całkowitego dla każdego żądania, dodaj losowy jitter do powtórzeń oraz ogranicz liczbę prób.
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())