Codes d’erreur et dépannage
Il y a ici deux familles d’erreurs, et elles ne se comportent pas de la même façon.
Les réponses de formule et de quota proviennent de la requête HTTP elle-même, avant une exécution ou à sa place. Elles portent un corps JSON avec un champ code, et chacune a une action précise qui la résout. Ce sont celles qu’un nouveau compte rencontre en premier : elles viennent donc en premier ci-dessous.
Les échecs d’exécution surviennent à l’intérieur d’une exécution acceptée et démarrée. Ils arrivent sous forme d’événement error sur le flux (ou sur l’exécution terminée) avec un error_code, et sont regroupés en cinq classes de récupération.
Réponses de formule et de quota
Lorsqu’une requête est refusée pour une raison liée à la formule, le corps de la réponse est un objet JSON portant un code. Branchez votre logique sur code, jamais sur le seul statut HTTP — le 429 est partagé entre le limiteur de débit (qui renvoie une chaîne simple) et le système de quotas (qui renvoie l’un de ces objets), et le 402 est partagé par plusieurs situations distinctes.
| Code | Statut | Ce qui s’est passé | Ce qui le résout |
|---|---|---|---|
quota_exceeded (scope: "month") | 429 | Vous avez utilisé toutes les questions incluses dans votre formule pour ce mois calendaire. Le corps porte limit, used et resets_at. | Attendez la remise à zéro du compteur, à 00:00 UTC le 1er du mois suivant, ou passez à une formule supérieure — le nouveau quota s’applique immédiatement. Sur une formule Team, le compteur est partagé par tout l’espace de travail : ajouter des sièges le relève donc aussi. |
quota_exceeded (scope: "day") | 429 | Pro et Team appliquent un plafond d’usage raisonnable de 500 questions par jour et par personne. Le corps porte resets_at. | Attendez la remise à zéro du plafond à minuit UTC. Votre quota mensuel reste intact. |
discovery_limit | 429 | Vous avez utilisé toutes les analyses IA du schéma incluses dans votre formule ce mois-ci. Le corps porte limit, used et resets_at. | Attendez la remise à zéro mensuelle, ou passez à une formule supérieure. Relancer une découverte de structure seule, reprendre une analyse à partir de son point de reprise et relancer une analyse qui réutilise l’introspection existante sont gratuits — seule une nouvelle analyse IA du schéma est décomptée. |
connection_limit | 402 | Créer, dupliquer ou activer une connexion dépasserait la limite de connexions actives de votre formule. Avec reason: "over_limit", cela signifie que vous détenez déjà plus de connexions actives que votre formule n’en autorise — typiquement après un passage à une formule inférieure — et les questions sont bloquées tant que vous n’êtes pas repassé sous la limite. | Mettez en pause une connexion dont vous n’avez pas besoin dans l’immédiat (page Connections, connexions, ou POST /api/v1/connections/{id}/paused), ou passez à une formule supérieure. La mise en pause conserve l’analyse IA du schéma et l’historique de la connexion. |
connection_paused | 402 | La connexion visée par cette requête est en pause. Une connexion en pause ne peut ni exécuter de questions ni lancer de découverte du schéma. | Réactivez-la depuis la page Connections — ce qui suppose de la place sous votre limite de connexions — ou visez une autre connexion. |
seats_full | 409 | Une invitation dépasserait le nombre de sièges de l’abonnement Team, ou l’espace de travail s’est rempli entre l’envoi de l’invitation et son acceptation. Le corps porte seats et members. | Ajoutez des sièges dans le portail client Stripe, ou retirez un membre ou une invitation en attente, puis renvoyez-la. |
team_min_seats | 422 | Un paiement Team a été demandé avec moins de 2 sièges. | Validez la commande avec au moins 2 sièges, ou choisissez Lite ou Pro pour un utilisateur unique. |
plan_blocked | 402 | Une action exigeant un abonnement Team actif a été tentée sans abonnement — inviter des coéquipiers est le cas que vous rencontrerez réellement. | Démarrez ou rétablissez un abonnement Team. Notez que ce code ne signifie jamais que votre compte est suspendu : un essai expiré ou un abonnement annulé vous ramène sur la formule Free, avec vos données intactes, et non dans un état bloqué. |
Deux choses à savoir sur le décompte des quotas :
- Les compteurs s’incrémentent lorsqu’une requête est acceptée : une exécution qui échoue ensuite consomme quand même une question.
- Si le magasin de compteurs est brièvement indisponible, les requêtes passent au lieu d’être refusées.
Les limites des formules elles-mêmes — combien de questions, de connexions et d’analyses IA du schéma chaque formule inclut — sont dans Facturation et formules.
Échecs d’exécution
Une fois l’exécution démarrée, les échecs sont classés en cinq classes, pour l’expérience de récupération :
- NO_RESULTS — la question a été comprise, mais n’a produit aucune donnée utile.
- TIMEOUT — l’exécution a dépassé sa limite de temps.
- PLAN_FAILURE — le modèle n’a pas pu produire de plan valide.
- CONNECTION_FAILURE — la base de données n’a pas pu être jointe.
- INTERNAL — le SQL ou le code généré était invalide, le bac à sable a planté, ou le modèle a renvoyé une sortie mal formée.
Chaque événement d’erreur du flux d’exécution porte un error_code qui correspond à une classe.
NO_RESULTS
| Code | Signification | Récupération |
|---|---|---|
MISSING_TABLE | Le SQL généré référence une table hors périmètre | Ajoutez la table manquante au périmètre et réessayez. |
MISSING_COLUMN | Le SQL généré référence une colonne qui n’existe pas | Vérifiez votre sélection de tables ou reformulez. |
TYPE_MISMATCH | La conversion implicite a échoué | Reformulez pour éviter de mélanger des types incompatibles. |
L’interface les présente sous forme de suggestions « élargissez votre question ».
TIMEOUT
| Code | Signification | Récupération |
|---|---|---|
SQL_TIMEOUT | La requête vers la base a dépassé la limite de temps de requête (30 secondes) | Ajoutez des filtres de date ou réduisez le périmètre. |
SANDBOX_TIMEOUT | L’étape Python du bac à sable a dépassé son plafond de temps réel (90 secondes) | Simplifiez l’analyse, ou réduisez le volume de données qu’elle traite. |
PLAN_FAILURE
| Code | Signification | Récupération |
|---|---|---|
NOT_ANSWERABLE | Le modèle a déterminé que la question ne peut pas être résolue avec les données du périmètre | Reformulez, ou faites entrer les tables manquantes dans le périmètre. |
AMBIGUOUS_QUERY | Plusieurs interprétations valides | Soyez plus précis. |
L’interface propose une nouvelle tentative modifiable — votre question reste dans le champ de saisie, prête à être révisée.
CONNECTION_FAILURE
| Code | Signification | Récupération |
|---|---|---|
CONNECTION_ERROR | Base de données injoignable | Testez depuis la barre latérale ; vérifiez les identifiants. |
La bannière de récupération de l’interface comporte un bouton Test connection (tester la connexion).
INTERNAL
| Code | Signification |
|---|---|
SQL_SYNTAX | Le SQL généré n’a pas pu être analysé |
SQL_VALIDATION | Le SQL généré n’a pas passé nos règles de validation |
SQL_EXECUTION | La base de données a renvoyé une erreur |
SANDBOX_CODE_ERROR | Le Python du bac à sable a levé une exception |
SANDBOX_OOM | Le Python du bac à sable a dépassé le plafond de mémoire |
LLM_INVALID_OUTPUT | Le modèle a renvoyé un plan qui ne correspondait pas à la structure requise |
La plupart déclenchent une correction puis une reprise automatique, dans des limites strictes. Une fois ce budget épuisé, vous voyez l’erreur sous-jacente.
Ressources liées
- Facturation et formules — ce que chaque formule inclut et comment mettre une connexion en pause libère un emplacement.
- Référence de l’API REST — les points de terminaison d’où proviennent ces réponses.
- Sécurité — pourquoi certaines questions sont refusées avant d’être exécutées.