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.
HTTP status
Dział zatytułowany „HTTP status”| Status | Znaczenie | Porady |
|---|---|---|
400 | Nieprawidłowe żądanie, na przykład wybrane ustawienie jest niedostępne | Popraw żądanie; nie ponawiaj próby |
401 | Brak, nieprawidłowe, wygasłe lub unieważnione poświadczenia | Zmień poświadczenia |
402 | Saldo (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. |
403 | Ograniczenia 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 |
404 | Zasób nie istnieje, został usunięty lub należy do innego konta (wszystkie trzy przypadki wyglądają identycznie) | Sprawdź identyfikator |
409 | Klucz 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ę. |
410 | Zasó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 |
413 | Plik lub treści żądania przekraczają limit | Użyj mniejszego pliku |
415 | Nieobsługiwany format pliku | Użyj innego formatu |
422 | Walidacja nie powiodła się, lub plik jest pusty lub nie zawiera żadnych danych do przetworzenia. | Popraw pola; nie ponawiaj automatycznie próby |
429 | Ograniczenie stawki, rozmiaru kolejki lub budżetu | Zobacz poniżej |
5xx | Temporary service error | Eksponencjalne wydłużanie czasu oczekiwania z maksymalną liczbą prób |
Obsługa 429
Dział zatytułowany „Obsługa 429”code | Znaczenie | Co zrobić |
|---|---|---|
RATE_LIMITED | Zbyt wiele żądań | Poczekaj na Retry-After, a następnie spróbuj ponownie |
CONCURRENCY_LIMITED | Zbyt wiele zadań tłumaczenia plików jest w kolejce. | Poczekaj na Retry-After lub na zakończenie niektórych zadań. |
AUTH_API_KEY_QUOTA_EXCEEDED | Budż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.
Strategia powtórnego próbowania
Dział zatytułowany „Strategia powtórnego próbowania”- Zapytania mogą być ponownie próbowane bezpośrednio.
- Podczas ponownego próbowania przesłania żądania utworzenia, użyj ponownie ten sam identyfikator
Idempotency-Keyi 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 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())