Erreurs et limites de l'API

Cette page documente le format des erreurs, la liste complète des codes de réponse, les limites de requêtes et comment l'utilisation du forfait affecte la traduction.

Enveloppe de réponse

Chaque réponse, succès ou erreur, utilise la même enveloppe JSON :

{
  "success": false,
  "data": null,
  "message": "Invalid source URL format.",
  "code": "TRANSLATION_INVALID_SOURCE_URL"
}

En cas d'erreur, success est false et data est null. Ramifiez sur le champ code plutôt que sur le message lisible par l'homme message, qui peut changer.

Codes d'erreur

Code	HTTP	Signification
CLÉ_API_MANQUANTE	401	Aucun en-tête X-API-Key n'a été fourni.
CLÉ_API_FORMAT_INVALIDE	401	La clé n'est pas d'un format reconnu.
CLÉ_API_MALFORMÉE	401	La clé n'a pas pu être analysée.
CLÉ_API_INVALIDE	401	La clé est bien formée mais n'est pas reconnue.
CLÉ_API_PROJET_INCOMPLET	500	Le site lié à cette clé est mal configuré. Contactez le support.
PROJET_NON_TROUVÉ	404	Aucun site ne correspond à cette clé.
PROJET_SUPPRIMÉ	404	Le site a été supprimé et n'est plus accessible.
URL_SOURCE_DE_TRADUCTION_INVALIDE	400	sourceUrl n'est pas une URL valide.
DIFFÉRENCE_DE_DOMAINE_URL_SOURCE_DE_TRADUCTION	403	sourceUrl ne correspond pas au domaine de votre site.
TRADUCTION_MÊME_LANGUE	400	La langue cible est identique à la langue source.
LANGUE_CIBLE_DE_TRADUCTION_NON_AUTORISÉE	403	La langue cible n'est pas activée pour votre site.
AUCUNE_LANGUE_DE_TRADUCTION_CONFIGURÉE	400	Aucune langue cible n'est configurée pour le site.
SERVICE_DE_TRADUCTION_INDISPONIBLE	503	Le service de traduction est temporairement indisponible. Réessayez avec un délai d'attente.
ÉCHEC_DU_SERVICE_DE_TRADUCTION	500	Le service de traduction n'a pas pu traiter la demande.
AUCUN_CONTENU_TRADUISIBLE	400	Aucun contenu traduisible n'a été trouvé dans le HTML.
LIMITE_DE_PLAN_ATTEINTE	403	La limite de mots de votre forfait est épuisée.
ERREUR_DE_VALIDATION	400	Le corps de la requête n'a pas réussi la validation du schéma.
JSON_INVALIDE	400	Le corps de la requête n'est pas un JSON valide.
ERREUR_DE_DÉCOMPRESSION	400	Un corps gzip n'a pas pu être décompressé.
REQUÊTE_TROP_VOLUMINEUSE	413	Le corps de la requête dépasse 5 Mo.
NON_TROUVÉ	404	Route inconnue.

Limites de requêtes

Limite	Valeur
Corps de requête maximum	5 Mo
Nombre maximum de chaînes par requête	500 (point de terminaison des chaînes)
Méthodes autorisées	GET, POST, OPTIONS

Si le corps dépasse 5 Mo, vous recevez REQUEST_TOO_LARGE (413). Pour les pages volumineuses ou les grands ensembles de chaînes, répartissez le travail sur plusieurs requêtes.

Corps de requête compressés

Le traducteur accepte les corps de requête compressés gzip. Définissez l'en-tête Content-Encoding sur gzip et envoyez le JSON compressé ; le corps est décompressé avant l'analyse. Ceci est utile pour les grands documents HTML qui approchent la limite de 5 Mo.

Content-Type: application/json
Content-Encoding: gzip

Si la décompression échoue, la réponse est DECOMPRESSION_ERROR (400).

Requêtes inter-origines

Le traducteur renvoie des en-têtes CORS permissifs, autorisant les requêtes de n'importe quelle origine avec les en-têtes Content-Type, X-API-Key et Content-Encoding. Même ainsi, les requêtes transportent votre clé API et doivent être envoyées côté serveur. Voir Authentification.

Utilisation du plan et traductions partielles

La traduction consomme l'allocation de mots de votre plan, partagée entre les points de terminaison HTML et chaînes. L'utilisation est appliquée par requête plutôt qu'en rejetant l'appel complet :

• Si votre allocation est épuisée avant l'arrivée d'une requête, la requête échoue avec PLAN_LIMIT_REACHED (403).
• Si l'allocation s'épuise à mi-chemin d'une requête, Universally traduit autant que possible, renvoie une réponse réussie et signale le déficit dans les métadonnées.

Deux champs de métadonnées décrivent cela :

Champ	Signification
limiteAtteinte	true lorsque l'allocation de mots a été atteinte pendant la requête.
chainesSautées	Le nombre de chaînes restantes dans la langue source car la limite a été atteinte.

Lorsque limitReached est true, traitez la réponse comme partielle : le contenu traduit est renvoyé si possible, et les chaînes non traduites reviennent à leur texte d'origine. Mettez à niveau votre plan pour augmenter l'allocation.

Nouvelles tentatives

Pour les erreurs transitoires (TRANSLATION_SERVICE_UNAVAILABLE à 503, ou tout 5xx), réessayez avec une exponentielle décroissante. Les traductions sont mises en cache, donc les requêtes retentées qui ont partiellement réussi auparavant réutilisent le travail existant et ne traduisent que ce qui manque encore. Ne retentez pas les erreurs 4xx ; elles indiquent un problème avec la requête qui ne se résoudra pas d'elle-même.