Référence complète de l'API : developer.universally.com contient la spécification en direct pour l'API Traducteur et l'API Plateforme, avec tous les champs, codes d'état et exemples de réponses. Cette page couvre ce qu'il faut savoir à ce sujet.
Chaque réponse utilise la même enveloppe, de sorte qu'un client se branche sur le champ code plutôt que sur le seul statut HTTP.
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 configurée pour votre site, ou vous avez envoyé un code de région alors qu'un code de variante était requis. |
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. |
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. |
ERREUR_INTERNE_DU_SERVEUR |
500 | Erreur serveur inattendue. Vous pouvez réessayer avec un délai d'attente. |
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 |
La limite de 5 Mo s'applique aux octets que vous envoyez, donc un corps gzippé est mesuré compressé. Si elle est dépassée, vous recevez REQUEST_TOO_LARGE (413). Pour les pages volumineuses ou les grands ensembles de chaînes, compressez le corps ou divisez 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. Comme la limite de taille compte les octets que vous envoyez, la compression permet de faire passer un document plusieurs fois plus volumineux que 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 déduit le total de mots de votre plan, partagé entre les points d'accès HTML et chaînes.
Dépasser la limite n'est pas une erreur. Il n'y a pas de code d'état pour cela : un espace de travail dépassant la limite reçoit toujours un 200, avec le déficit signalé dans les métadonnées. La limite est vérifiée une seule fois, à l'arrivée de la requête, de sorte qu'une requête qui commence sous la limite termine tout ce dont elle a besoin, même si cela la fait dépasser le total.
| Champ | Signification |
|---|---|
limiteAtteinte |
true si l'espace de travail était déjà à sa limite de mots ou au-dessus à l'arrivée de la requête. |
chainesSautées |
Le nombre de chaînes laissées non traduites en conséquence. |
Lorsque limitReached est true, traitez la réponse comme partielle. Tout ce qui a déjà été traduit est toujours renvoyé depuis le stockage ; tout ce qui aurait nécessité une nouvelle traduction ne l'est pas. Sur le point d'accès HTML, ce texte reste dans la langue source dans le document renvoyé. Sur le point d'accès des chaînes, ces clés sont absentes de la carte translations, vous devez donc vous rabattre sur votre propre texte source pour toute clé que vous ne recevez pas en retour. Voir Traduire des chaînes.
Augmentez le total avec un complément de mots ou un plan plus important. Voir Limites d'utilisation.
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.