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.
Stato HTTP
Sezione intitolata “Stato HTTP”| Stato | Significato | Consigli |
|---|---|---|
400 | Richiesta non valida; ad esempio, l’impostazione selezionata non è disponibile. | Correggi la richiesta; non riprovare |
401 | Credenziale mancante, non valida, scaduta o revocata | Modifica le credenziali |
402 | Il 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 |
403 | I 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 |
404 | La risorsa non esiste, è stata eliminata o appartiene a un altro account (tutte e tre le condizioni appaiono identiche) | Verifica l’ID |
409 | La chiave di idempotenza è stata utilizzata per una richiesta diversa, oppure lo stato della risorsa non consente l’operazione. | Interroga l’operazione originale, quindi decidi |
410 | La 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 |
413 | Il file o il corpo della richiesta supera il limite | Utilizza un file più piccolo |
415 | Formato file non supportato | Utilizzare un altro formato |
422 | Convalida non riuscita, oppure il file è vuoto o non contiene nulla da elaborare. | Correggi i campi; non riprovare automaticamente |
429 | Tasso, dimensione della coda o budget limitati | Vedi sotto |
5xx | Errore temporaneo del servizio | Ritrasmissione con backoff esponenziale e numero massimo di tentativi |
Gestione 429
Sezione intitolata “Gestione 429”code | Significato | Cosa fare |
|---|---|---|
RATE_LIMITED | Troppe richieste | Attendere Retry-After, quindi riprovare |
CONCURRENCY_LIMITED | Troppi lavori di traduzione dei file sono in coda | Attendere Retry-After o l’eventuale completamento di alcuni processi |
AUTH_API_KEY_QUOTA_EXCEEDED | Il budget della chiave è esaurito | Non riprovare finché il budget non viene aumentato |
Un 429 privo di Retry-After dovrebbe essere gestito con un backoff esponenziale.
Strategia di retry
Sezione intitolata “Strategia di retry”- Le query possono essere riprovate direttamente.
- Quando si ripete una richiesta di creazione, riutilizzare lo stesso
Idempotency-Keye 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 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())