Erreurs et codes de statut
Interprétez les réponses d’erreur de l’API, reprenez les requêtes qui ont échoué et distinguez les échecs HTTP des échecs de traduction.
Vérifiez le statut HTTP avant de décoder une réponse réussie. L’API à l’adresse https://api.lingo.dev/v2 signale les échecs sous forme de détails de problème en JSON. Une tâche récupérée avec succès peut néanmoins faire état d’un travail qui a échoué : vérifiez donc aussi son statut.
Lire une réponse d’erreur #
Les réponses d’erreur utilisent Content-Type: application/problem+json. Les champs courants sont type, title, status et detail ; les problèmes nommés comportent aussi des champs qui identifient la ressource concernée ou la mesure corrective.
Cet exemple correspond à une tâche de localisation introuvable :
{
"type": "https://lingo.dev/docs/api/errors/localization-job-not-found",
"title": "Localization job not found",
"status": 404,
"detail": "Localization job lfr_example not found.",
"id": "lfr_example"
}L’URI type identifie le problème. Consultez le catalogue des erreurs de l’API pour connaître les champs et les points de terminaison associés à chaque problème nommé. Conservez l’URI renvoyée telle quelle lorsque vous enregistrez ou classez une erreur.
Corriger une requête non valide #
Une requête qui ne passe pas la validation renvoie 400 Requête incorrecte avec type: "about:blank". Lorsque des détails de validation sont disponibles, errors répertorie les champs path et message de chaque problème :
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Request validation failed",
"errors": [
{
"path": ["payload", "documents", 0, "source"],
"message": "Expected a JSON object"
}
]
}Le chemin commence par la partie de la requête soumise à validation, par exemple payload, suivie des noms de propriétés et des indices de tableau commençant à zéro. Cet exemple identifie source dans la première entrée documents du corps de la requête. Corrigez la valeur indiquée conformément au schéma du point de terminaison avant de renvoyer la requête. about:blank est un type de problème générique : il ne figure donc pas dans le catalogue des erreurs nommées.
Choisir la procédure de reprise #
| Statut HTTP | Cause habituelle | Action à effectuer |
|---|---|---|
| 400 | La requête ne respecte pas le schéma de la route. | Corrigez le chemin, les paramètres de requête, les en-têtes ou le corps à l’aide des détails de validation fournis. |
| 401 | Informations d’authentification absentes, non valides ou expirées. | Chargez la clé prévue ou renouvelez la session utilisateur. |
| 402 | Crédits insuffisants, fonctionnalités indisponibles dans l’offre ou clé de service désactivée après une réduction des droits RBAC. | Consultez la condition identifiée et satisfaites à l’exigence liée au compte ou à l’offre. |
| 403 | Autorisation manquante, identité utilisateur requise ou restriction liée à un indicateur de fonctionnalité. | Vérifiez l’appelant et les exigences d’accès de l’opération. |
| 404 | La ressource n’existe pas ou n’est pas visible pour cet appelant. | Vérifiez l’identifiant, l’organisation et les autorisations de la ressource. |
| 409 | L’opération entre en conflit avec l’état de la ressource. | Consultez l’état actuel de la ressource. Téléversez les artefacts manquants, terminez le travail en cours ou actualisez une relecture clôturée, selon les indications. |
| 413 | Un téléversement ou le corps d’une requête dépasse la limite de taille. | Réduisez les données d’entrée ou divisez le travail ; chaque artefact téléversé peut atteindre 25 Mio. |
| 422 | La structure de la requête est valide, mais celle-ci ne respecte pas les contraintes d’une opération. | Corrigez la condition identifiée, par exemple une modification non valide lors d’une relecture ou une clé d’idempotence réutilisée. |
| 429 | Une limite d’utilisation ou d’opérations a été atteinte. | Respectez le délai indiqué dans le problème avant de réessayer, s’il est fourni ; sinon, vérifiez la limite du compte avant toute nouvelle tentative. |
| 5xx | Un serveur ou une dépendance n’a pas pu traiter la requête. | Conservez les identifiants de la ressource et de la requête ; ne réessayez que si la sémantique de l’opération le permet. |
detail précise la nature de l’échec ; le statut seul ne suffit pas à le classer. Les réponses provenant d’un proxy ou liées à une défaillance réseau peuvent ne pas contenir de détails de problème dans leur corps. Conservez leur statut HTTP et le texte lisible de la réponse pour établir un diagnostic, sans consigner de secrets dans les journaux.
Réessayer une soumission de localisation #
Enregistrez la valeur Idempotency-Key de la requête de création avant de l’envoyer. Si la réponse est perdue, renvoyez la même requête de création avec cette clé pour récupérer la tâche d’origine. Une nouvelle clé crée un nouveau travail.
Après la création, enregistrez l’identifiant de la tâche. Consultez cette tâche avant de décider d’en créer une autre. Les téléversements utilisent les octets exacts désignés par leur adresse SHA-256 ; effectuez tous les téléversements manquants avant de démarrer. Répéter /start agit sur la même tâche.
Les contrôles d’admission ont lieu au démarrage. DailyTokenLimitReached ou un manque de crédits laissent la tâche en attente : elle pourra démarrer ultérieurement, une fois la condition liée au compte résolue. Créer de nouvelles tâches à répétition ne permet pas de résoudre une limite de compte.
Distinguer l’échec d’une requête de l’échec du travail #
Un statut HTTP 200 renvoyé par GET /v2/localization/jobs/:id signifie que la tâche a été récupérée. Son status._tag peut néanmoins être Failed. Consultez status.message, le statut de chaque cible et les avertissements et échecs des étapes.
Les cibles terminées restent téléchargeables même si une autre cible échoue. Conservez-les et, après avoir corrigé la cause, soumettez uniquement le travail à régénérer. L’expiration du délai d’interrogation côté client n’annule pas la tâche.
Le provisionnement dispose de ses propres résultats par type et procédures de reprise. Les décisions de relecture ont leurs propres erreurs de relecture clôturée et de modification non valide. Appuyez-vous sur l’état de ces ressources pour la reprise, plutôt que de considérer chaque échec comme une raison de répéter l’écriture initiale.