Erreurs
Gérez les échecs de l’API AI Glot à l’aide de codes d’erreur stables, d’identifiants de requête, de conseils de nouvelle tentative et d’explications détaillées pour chaque erreur documentée.
Toutes les erreurs de l’API utilisent le même format. Fondez votre logique sur error.code, jamais sur le message destiné aux utilisateurs.
{
"error": {
"type": "permission_error",
"code": "insufficient_scope",
"message": "This credential is missing the batches:write scope.",
"docs_url": "https://ai-glot.com/docs/api/errors#insufficient_scope"
},
"request_id": "req_example"
}Codes d’état
| Statut | Signification | Action à effectuer |
|---|---|---|
| 400 | Requête mal formée ou champ inconnu | Corrigez la requête |
| 401 | Identifiant d’authentification manquant, invalide, expiré ou révoqué | Remplacez-le ou renouvelez-le |
| 403 | Authentification réussie, mais accès non autorisé | Accordez l’autorisation requise ou activez la fonctionnalité |
| 404 | Ressource inexistante ou hors de cet espace de travail | Vérifiez l’identifiant et l’espace de travail |
| 409 | L’état actuel est incompatible avec la requête | Consultez la ressource, puis décidez de la marche à suivre |
| 413 | Corps de requête trop volumineux | Envoyez un corps plus petit |
| 422 | Valeur bien formée, mais invalide | Corrigez la valeur indiquée |
| 429 | Limite de requêtes atteinte | Attendez Retry-After |
| 500/503 | AI Glot a rencontré une erreur ou est temporairement indisponible | Réessayez en espaçant les tentatives |
Codes d’authentification et d’autorisation
authentication_required
Aucun identifiant d’authentification de type bearer n’a été envoyé. Ajoutez l’en-tête Authorization.
invalid_api_key
La clé est mal formée ou inconnue. Vérifiez que vous avez copié la valeur aig_live_… en entier.
api_key_expired
La clé a atteint sa date d’expiration configurée. Créez-en une nouvelle ou utilisez une autre clé.
api_key_revoked
Un administrateur a révoqué ou renouvelé cette clé. Mettez à jour l’intégration avec un identifiant d’authentification actif.
insufficient_scope
L’identifiant d’authentification a été validé, mais ne dispose pas de l’autorisation requise pour cette opération.
feature_not_available
L’offre de l’espace de travail ou la version actuelle de la plateforme ne comprend pas la fonctionnalité demandée.
admin_required
Seul un administrateur de l’espace de travail peut effectuer cette opération.
Codes de requête
invalid_request
La requête ne peut pas être analysée ou ne respecte pas le contrat du point de terminaison.
unknown_field
Une propriété du corps JSON n’est pas reconnue. Corrigez son orthographe au lieu de désactiver la validation. Les paramètres de requête non reconnus ne déclenchent pas cette erreur : ils sont ignorés. Ainsi, un filtre mal orthographié renvoie une réponse 200 sans filtrage.
invalid_parameter
Un paramètre a un type, une plage ou un format incorrect.
invalid_cursor
Le curseur de pagination est invalide. Réutilisez next_cursor exactement tel qu’il a été renvoyé.
request_too_large
Le corps de la requête dépasse la limite stricte du point de terminaison.
Codes de ressource et d’état
batch_not_found
Aucune traduction visible ne porte cet identifiant. Les ressources d’un autre espace de travail renvoient volontairement la même erreur.
glossary_not_found
Aucun glossaire n’existe pour cette paire de langues.
resource_not_found
La ressource ou la route demandée n’existe pas.
glossary_already_exists
Un glossaire existe déjà pour cette paire de langues. Mettez-le à jour au lieu d’en créer un autre.
result_not_ready
La traduction n’est pas terminée. Aucun résultat ne peut donc être téléchargé pour le moment.
batch_not_editable
L’état actuel de la traduction ne permet pas la modification administrative demandée.
idempotency_key_reused
L’Idempotency-Key a déjà servi pour une autre requête (autre fichier, autre nom ou autre consigne). Renvoyez la même requête pour la répéter, ou une nouvelle clé pour un nouveau travail. Voir Créer une traduction.
Codes de fichier et de format
unsupported_format
L’extension du fichier ne fait pas partie des formats acceptés par AI Glot. Consultez Fichiers et formats pour connaître tous les formats pris en charge et leurs extensions.
file_too_large
Le fichier dépasse la limite associée à son format. Les limites sont propres à chaque format et non globales (60 MB pour CSV, 4 MB pour un catalogue PO). Une taille acceptée pour une extension peut donc être refusée pour une autre.
file_fetch_failed
Impossible de récupérer file_url. L’URL doit utiliser HTTPS et pointer vers la destination finale : les redirections ne sont pas suivies. Un lien raccourci ou signé qui redirige ensuite échoue donc ici.
file_retention_expired
La période de conservation du fichier téléversé a pris fin et celui-ci n’est plus stocké. Relancez la traduction à partir du fichier source.
file_expired
Le fichier associé à cette traduction n’existe plus. L’opération ne peut donc pas se poursuivre.
result_too_large
La traduction terminée dépasse la taille maximale des résultats renvoyés. Divisez le fichier source et traduisez-le en plusieurs parties.
Codes de forfait et d’approbation
plan_invalid
L’instruction ou son affinement n’a pas pu être converti en plan exploitable. Aucun frais n’a été facturé. Lorsque la cause est connue, le message l’indique : aucun élément du fichier ne correspondait à l’instruction, celle-ci demande d’écrire à un emplacement que le fichier ne permet pas de modifier, ou le plan n’a pas pu être généré cette fois-ci (renvoyez la même instruction). Sinon, reformulez-la : il est plus fiable d’indiquer les champs ou les colonnes à traduire que de les décrire.
plan_changed
La valeur expected_plan_revision fournie ne correspond pas au plan actuel pouvant être examiné, ou cette révision ne peut pas être vérifiée. Cette approbation n’a pas lancé de nouveau traitement. Récupérez à nouveau le lot, vérifiez son périmètre actuel, les exclusions et le coût calculé, puis décidez si vous souhaitez approuver la nouvelle révision. Ne relancez pas l’ancienne approbation sans vérification.
no_plan_yet
L’approbation a été demandée avant la création du plan. Appelez d’abord POST /v1/batches/{batch_id}/plan. Cette vérification empêche une intégration de facturer un espace de travail pour une traduction qui n’a jamais été décrite.
batch_not_awaiting_approval
La traduction n’est pas dans un état qui permet son approbation. Elle est généralement déjà en cours ou terminée. Appelez plutôt GET /v1/batches/{batch_id} pour en vérifier l’état.
insufficient_credits
Le solde de l’espace de travail ne couvre pas le coût calculé du plan (HTTP 402). Aucun crédit n’est réservé. La traduction pourra donc être approuvée dès que des crédits auront été ajoutés.
L’erreur contient un objet payment, aussi bien dans l’API REST que dans l’outil MCP approve_translation :
"payment": {
"credits_needed": 30000,
"credit_balance": 5000,
"credits_missing": 25000,
"credits_to_buy": 25000,
"price_eur": 25,
"payment_url": "https://app.ai-glot.com/w/<workspace_id>/new?continue=<batch_id>&pay=1",
"plans": [
{ "plan": "Starter", "eur_per_month": 42, "credits_per_month": 100000 },
{ "plan": "Pro", "eur_per_month": 199, "credits_per_month": 1000000 }
]
}credits_to_buy correspond au plus petit achat permettant de couvrir le manque (le montant minimal d’achat s’applique). payment_url ouvre cette traduction dans AI Glot et affiche directement la fenêtre d’achat : montant exact, packs de crédits, forfaits et échantillon gratuit si l’espace de travail y a droit. Le lien ne fonctionne que pour un membre connecté à l’espace de travail ; vous pouvez donc le partager sans risque. plans répertorie les forfaits mensuels, plus avantageux par crédit pour les personnes qui traduisent régulièrement. Ils apparaissent sur la même page, sous l’achat ponctuel.
Un agent doit demander l’accord de l’utilisateur avant de lui proposer le lien et ne doit jamais payer à sa place. Une fois le paiement effectué, il doit vérifier le solde avec GET /v1/account, puis soumettre à nouveau l’approbation après confirmation de l’utilisateur. Celui-ci peut aussi lancer la traduction depuis cette page.
Codes de langue et de glossaire
language_not_supported
La balise ne figure pas dans le catalogue des langues prises en charge. Consultez GET /v1/languages.
invalid_language_pair
L’identifiant de la paire de langues ne peut pas être décomposé en deux balises BCP 47 prises en charge.
glossary_term_limit_reached
Le nombre de termes obtenu dépasserait la limite autorisée par l’offre de l’espace de travail. La mise à jour est atomique : aucune modification n’a été effectuée.
glossary_limit_reached
L’espace de travail a atteint le nombre maximal de glossaires prévu par l’offre actuelle.
invalid_glossary_terms
Une ou plusieurs entrées du glossaire sont vides, incomplètes ou autrement invalides.
Codes de service
rate_limited
L’identifiant d’authentification a dépassé la limite autorisée sur une période donnée. Attendez le délai indiqué par Retry-After, puis réessayez en ajoutant une temporisation aléatoire.
internal_error
AI Glot a rencontré une erreur inattendue. Réessayez en espaçant les tentatives et conservez le request_id.
service_unavailable
Un service nécessaire est temporairement indisponible. Réessayez en espaçant les tentatives.