Erreurs et retours
Les erreurs métier renvoient code et message au niveau supérieur du corps de la réponse. detail est généralement identique à message, mais peut être une explication différente et plus concise (comme ci-dessous) ; affichez message aux utilisateurs. Les messages sont en chinois :
{ "code": "CONCURRENCY_LIMITED", "message": "排队中的文件已达上限(1000 个),请等部分文件翻译完成后再提交", "detail": "排队文件完成一部分后可继续提交"}Quelques erreurs métier ne renvoient que code. Les échecs de validation renvoient 422 accompagné d’une liste des erreurs de champ dans detail :
{ "detail": [ { "loc": ["body", "target_lang"], "msg": "Field required", "type": "missing" } ]}Traitez d’abord les erreurs via le statut HTTP, puis via code : de nombreuses erreurs ne renvoient que le code générique UNKNOWN_ERROR, et seules certaines comportent un code spécifique code (comme les 429 cas ci-dessous). Enregistrez l’en-tête de réponse X-Request-Id pour le dépannage.
Statut HTTP
Section intitulée « Statut HTTP »| État | Signification | Conseils |
|---|---|---|
400 | Demande invalide, par exemple lorsque le paramètre choisi n’est pas disponible. | Corrigez la requête ; ne réessayez pas |
401 | Informations d’identification manquantes, invalides, expirées ou révoquées | Modifier les informations d’identification |
402 | Le solde (après déduction des dettes) n’excède pas le seuil de charge, ou il est négatif ; avec une clé API, le budget restant de la clé peut être trop faible. | Rechargez (ou augmentez le budget de la clé), puis soumettez à nouveau. |
403 | Les limites de la clé n’autorisent pas cette opération (par exemple, le paramètre de traduction n’est pas autorisé), le compte est désactivé ou l’opération doit être effectuée dans un navigateur connecté (comme la gestion des clés API). | Vérifiez les paramètres clés ou utilisez le site web |
404 | La ressource n’existe pas, a été supprimée ou appartient à un autre compte (les trois cas se présentent de la même manière) | Vérifiez l’ID |
409 | La clé d’idempotence a été utilisée pour une requête différente, ou l’état de la ressource ne permet pas l’opération. | Interrogez l’opération d’origine, puis décidez |
410 | La ressource ou le point de terminaison est définitivement indisponible, par exemple un point de terminaison retiré ou une tâche supprimée associée à une clé d’idempotence. | Ne pas réessayer |
413 | Le fichier ou le corps de la requête dépasse la limite | Utilisez un fichier plus petit |
415 | Format de fichier non pris en charge | Utilisez un autre format |
422 | Échec de la validation, ou le fichier est vide ou ne contient rien à traiter. | Corrigez les champs ; ne relancez pas automatiquement |
429 | Taux, taille de la file d’attente ou budget limité | Voir ci-dessous |
5xx | Erreur temporaire du service | Réessai exponentiel avec un nombre maximal de tentatives |
Gestion du code 429
Section intitulée « Gestion du code 429 »code | Signification | Que faire |
|---|---|---|
RATE_LIMITED | Trop de requêtes | Attendez Retry-After, puis réessayez |
CONCURRENCY_LIMITED | Trop de tâches de traduction de fichiers sont en attente. | Attendez Retry-After, ou que certains travaux se terminent |
AUTH_API_KEY_QUOTA_EXCEEDED | Le budget de la clé est épuisé | N’effectuez aucun nouveau tentative tant que le budget n’a pas été augmenté. |
Un 429 sans Retry-After doit être traité avec une rétroaction exponentielle.
Stratégie de retry
Section intitulée « Stratégie de retry »- Les requêtes peuvent être réessayées directement.
- Lors d’une nouvelle tentative de requête de création, réutilisez le même
Idempotency-Keyet exactement le même corps ; utilisez une nouvelle clé pour chaque nouvel envoi. - En cas d’échec du téléchargement, demandez une nouvelle adresse de téléchargement.
- Définissez les délais de connexion, de lecture et globaux pour chaque requête, ajoutez une variation aléatoire aux retours automatiques et limitez le nombre de tentatives.
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())