Aller au contenu

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.

ÉtatSignificationConseils
400Demande invalide, par exemple lorsque le paramètre choisi n’est pas disponible.Corrigez la requête ; ne réessayez pas
401Informations d’identification manquantes, invalides, expirées ou révoquéesModifier les informations d’identification
402Le 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.
403Les 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
404La 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
409La 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
410La 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
413Le fichier ou le corps de la requête dépasse la limiteUtilisez un fichier plus petit
415Format de fichier non pris en chargeUtilisez 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
429Taux, taille de la file d’attente ou budget limitéVoir ci-dessous
5xxErreur temporaire du serviceRéessai exponentiel avec un nombre maximal de tentatives
codeSignificationQue faire
RATE_LIMITEDTrop de requêtesAttendez Retry-After, puis réessayez
CONCURRENCY_LIMITEDTrop de tâches de traduction de fichiers sont en attente.Attendez Retry-After, ou que certains travaux se terminent
AUTH_API_KEY_QUOTA_EXCEEDEDLe 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.

  • 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-Key et 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 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())