AI Glot websiteOpen AI Glot
API RESTErreurs

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.

Exemple d’erreur
{
  "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

StatutSignificationAction à effectuer
400Requête mal formée ou champ inconnuCorrigez la requête
401Identifiant d’authentification manquant, invalide, expiré ou révoquéRemplacez-le ou renouvelez-le
403Authentification réussie, mais accès non autoriséAccordez l’autorisation requise ou activez la fonctionnalité
404Ressource inexistante ou hors de cet espace de travailVérifiez l’identifiant et l’espace de travail
409L’état actuel est incompatible avec la requêteConsultez la ressource, puis décidez de la marche à suivre
413Corps de requête trop volumineuxEnvoyez un corps plus petit
422Valeur bien formée, mais invalideCorrigez la valeur indiquée
429Limite de requêtes atteinteAttendez Retry-After
500/503AI Glot a rencontré une erreur ou est temporairement indisponibleRé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 :

JSON
"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.

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search AI Glot Docs documentation and read it in full, instead of answering from memory.

https://ai-glot.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://ai-glot.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.