Salta ai contenuti

Errori e ripetizioni

Gli errori aziendali restituiscono code e message al livello principale del corpo della risposta. detail è solitamente identico a message, ma può essere una spiegazione diversa e più breve (come mostrato di seguito); mostrare message agli utenti. I messaggi sono in cinese:

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

Alcuni errori aziendali restituiscono solo code. Gli errori di convalida restituiscono 422 con un elenco degli errori dei campi in detail:

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

Gestire gli errori prima tramite lo stato HTTP, quindi tramite code: molti errori restituiscono solo il generico UNKNOWN_ERROR, e solo alcuni riportano un code specifico (come i 429 casi riportati di seguito). Registrare l’intestazione di risposta X-Request-Id per la risoluzione dei problemi.

StatoSignificatoConsigli
400Richiesta non valida; ad esempio, l’impostazione selezionata non è disponibile.Correggi la richiesta; non riprovare
401Credenziale mancante, non valida, scaduta o revocataModifica le credenziali
402Il saldo (al netto dei debiti) non supera la soglia di spesa, oppure è negativo; con una chiave API, il budget residuo della chiave potrebbe essere troppo basso.Ricarica (o aumenta il budget della chiave), quindi invia di nuovo
403I limiti della chiave non consentono questa operazione (ad esempio, l’impostazione di traduzione non è consentita), l’account è disabilitato o l’operazione deve essere eseguita in un browser con accesso effettuato (come nella gestione delle chiavi API).Verifica le impostazioni principali o utilizza il sito web
404La risorsa non esiste, è stata eliminata o appartiene a un altro account (tutte e tre le condizioni appaiono identiche)Verifica l’ID
409La chiave di idempotenza è stata utilizzata per una richiesta diversa, oppure lo stato della risorsa non consente l’operazione.Interroga l’operazione originale, quindi decidi
410La risorsa o l’endpoint è definitivamente non più disponibile, ad esempio un endpoint dismesso o un job eliminato associato a una chiave di idempotenza.Non riprovare
413Il file o il corpo della richiesta supera il limiteUtilizza un file più piccolo
415Formato file non supportatoUtilizzare un altro formato
422Convalida non riuscita, oppure il file è vuoto o non contiene nulla da elaborare.Correggi i campi; non riprovare automaticamente
429Tasso, dimensione della coda o budget limitatiVedi sotto
5xxErrore temporaneo del servizioRitrasmissione con backoff esponenziale e numero massimo di tentativi
codeSignificatoCosa fare
RATE_LIMITEDTroppe richiesteAttendere Retry-After, quindi riprovare
CONCURRENCY_LIMITEDTroppi lavori di traduzione dei file sono in codaAttendere Retry-After o l’eventuale completamento di alcuni processi
AUTH_API_KEY_QUOTA_EXCEEDEDIl budget della chiave è esauritoNon riprovare finché il budget non viene aumentato

Un 429 privo di Retry-After dovrebbe essere gestito con un backoff esponenziale.

  • Le query possono essere riprovate direttamente.
  • Quando si ripete una richiesta di creazione, riutilizzare lo stesso Idempotency-Key e lo stesso corpo esatto; utilizzare una nuova chiave per ogni nuovo invio.
  • In caso di caricamento non riuscito, richiedi un nuovo indirizzo di caricamento.
  • Imposta i timeout di connessione, lettura e totale per ogni richiesta, aggiungi una jitter casuale ai retry e limita il numero di tentativi.
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())