Aller au contenu
VELA
ENEssayer Vela
DÉVELOPPEURSL’essentiel en 2 min

Erreurs, statuts et reprises

Le statut HTTP de chaque échec et ce qu’il est sûr de réessayer.

À l’arrivée

Votre intégration réagit correctement à chaque type d’échec.

01 Les étapes02 À vérifier03 Pour aller plus loin
INPUT_ERRORCorriger les entrées
AUTH_ERRORRétablir la connexion
API_CHANGEDConsulter la réparation
EXECUTION_ERRORExaminer le résultat

Résultat d’une écriture inconnu ? Vérifiez le site avant de relancer.

Illustration du parcours · données d’exemple

Votre parcours, en trois étapes.

  1. 01

    Lisez le statut et le corps

    Une clé invalide renvoie un champ error simple. Un refus 429 ajoute un message. Ces réponses n’ont pas le champ success d’une exécution.

  2. 02

    Traitez la cause avant de relancer

    Corrigez les entrées, restaurez la connexion ou attendez la réparation selon le code. Une erreur d’exécution ne garantit pas qu’une reprise soit sûre.

  3. 03

    Ne répétez jamais une écriture au résultat inconnu

    Vérifiez l’enregistrement dans le logiciel cible avant de renvoyer quoi que ce soit.

Un point à approfondir ?

Ouvrez uniquement le sujet dont vous avez besoin.

Vue d’ensemble

Deux choses déterminent le comportement de votre intégration quand un connecteur échoue : lequel des quatre codes est revenu, et si la requête peut être renvoyée sans risque. Cette page couvre les deux, et nomme le seul cas où réessayer est une erreur alors que tout semble réessayable.

Les statuts
HTTPQuandCorps
200Le connecteur s’est exécuté et a répondu.L’enveloppe, avec success: true.
400Une entrée manque, ou le site a refusé la valeur.L’enveloppe, error.code vaut INPUT_ERROR.
400Le connecteur est inactif ou le corps de la requête est invalide.{ error, message }, avec BRIDGE_NOT_ACTIVE ou VALIDATION_ERROR.
401La clé manque ou est fausse, ou le connecteur n’a pas pu agir en tant qu’utilisateur connecté.Un simple { "error": "…" } pour une clé absente ou fausse ; l’enveloppe avec AUTH_ERROR quand c’est la connexion elle-même qui a échoué.
403Le compte a atteint une limite d’utilisation ou de l’offre.{ error, message } avec la raison du refus.
404Le connecteur demandé n’existe pas.{ "error": "NOT_FOUND", "message": "…" }.
429Limite de débit, ou cinq exécutions déjà en cours pour le compte.{ "error": "TOO_MANY_REQUESTS", "message": "…" } — pas l’enveloppe.
500Tout le reste : le site a changé, un délai dépassé, un échec de transport.L’enveloppe, error.code vaut API_CHANGED ou EXECUTION_ERROR.

Certains refus n’utilisent pas l’enveloppe d’exécution

Une clé absente ou invalide renvoie { error }. Les limites de débit, connecteurs inactifs, requêtes invalides et limites d’offre peuvent renvoyer { error, message }, sans success. Vérifiez le statut HTTP et la forme du corps avant de lire le résultat d’une exécution.

La politique de reprise
CodeRéessayer ?Comment
INPUT_ERRORNon.La même entrée échouera à l’identique. error.availableOptions liste souvent des valeurs qui passeraient ; error.sampleInput montre la forme attendue.
AUTH_ERRORAprès rétablissement de l’accès.Lisez l’état du connecteur et terminez la reconnexion si elle est demandée. Une simple pause ne prouve pas que l’accès est rétabli.
API_CHANGEDAprès vérification.Consultez l’état de la réparation. Elle peut être en cours ou demander votre intervention ; attendez un résultat vérifié avant de rappeler.
EXECUTION_ERRORSeulement si la reprise est sûre.Ce code couvre des incidents passagers et des erreurs d’exécution. Pour une lecture, quelques tentatives espacées peuvent aider. Pour une écriture au résultat inconnu, arrêtez et vérifiez le site source.
429Oui.Respectez Retry-After quand il est présent. Pour le refus de concurrence il n’y a pas d’en-tête : attendez la fin de vos propres appels en cours. Rien n’est mis en file pour vous.
La règle qui compte plus que les codes

Ne réessayez jamais une action dont vous ne voyez pas le résultat

Quand un connecteur qui modifie quelque chose a envoyé sa requête et que la réponse n’est jamais arrivée, personne ne peut distinguer une réservation qui a échoué d’une réservation que votre client détient. Vela traite cet état comme définitif : aucune réparation, aucune reprise. Votre intégration doit faire pareil — lisez l’enregistrement sur le site, puis décidez.

Vela ne garantit pas l’idempotence des écritures. Envoyer deux fois la même requête peut créer deux enregistrements. Ne supposez pas qu’un en-tête d’idempotence est pris en charge sans indication explicite dans le contrat du connecteur.

Les champs à lire
Enveloppe d’échec 
{
  "success": false,
  "data": null,
  "error": {
    "code": "INPUT_ERROR",
    "message": "no practitioner named \"Ana\" on this account",
    "availableOptions": ["Anna", "Anaïs"],
    "sampleInput": { "practitioner": "Anna", "date": "2026-09-21" }
  },
  "meta": { "executionId": "9e600e25-…", "scriptVersion": 3, "durationMs": 412, "sessionRenewed": false },
  "needsRepair": false
}
  • meta.executionId — à citer dans une demande de support. Il identifie l’exécution, son entrée et la version qui a répondu.
  • meta.scriptVersion — quelle version a produit ce résultat, pour qu’une vieille réponse reste explicable.
  • meta.sessionRenewed — true quand Vela s’est reconnecté pendant cet appel précis. Utile quand vous cherchez d’où vient une latence : cet appel-là a payé une reconnexion.
  • needsRepair — la classification de l’erreur indique un échec réparable. Cela ne prouve pas qu’une réparation a démarré ou réussi : consultez l’état du connecteur. Une écriture au résultat inconnu bloque la réparation automatique.
Attendre la réponse

Chaque appel répond avec son résultat. ?async=true est accepté pour les anciennes intégrations et reçoit la même réponse. Pour suivre les étapes au fil de l’eau, utilisez /stream.

Ce qu’un échec provoque côté Vela
  • Un API_CHANGED sur un connecteur sain lance une réparation automatique. Un AUTH_ERROR fait se reconnecter Vela une fois, puis vous le demande. Une écriture au résultat inconnu ne lance jamais rien d’automatique.
  • Un 429, un délai dépassé ou un échec réseau ne change rien à l’état du connecteur. Les échecs ambigus ne sont jamais retenus contre lui.
  • Un INPUT_ERROR n’est pas une faute du tout : le connecteur a fonctionné, le site a dit non.

Les états qui en découlent sont décrits dans Le cycle de vie d’un connecteur, et la suite dans La réparation automatique.

LA SUITEConnecter un client MCP

Une adresse de serveur pour les outils de votre toolset.

Votre situation ne correspond pas au guide ?

Échanger avec l’équipe ↗