Erreurs

L'API utilise les codes de statut HTTP standard. Le corps d'une réponse en échec contient un seul champ, error, dont le texte décrit la cause :

{ "error": "Clé API invalide" }

Ce message est destiné au développeur, pas à l'utilisateur final : il peut évoluer, et ne doit donc pas servir de valeur de test. Branchez votre logique sur le code de statut.

Codes retournés

Statut	Cause	Conduite à tenir
400	Corps ou paramètre invalide	Corriger la requête ; réessayer à l'identique échouera
401	Clé absente, inconnue ou révoquée	Vérifier l'en-tête X-API-Key
403	Clé valide mais sans le droit demandé, ou appelée depuis une IP non autorisée	Vérifier le périmètre et la restriction d'IP de la clé
404	Ressource inexistante, ou appartenant à un autre compte	Ne pas distinguer les deux cas : la réponse est volontairement identique
429	Plafond de requêtes atteint	Attendre, puis réessayer avec un backoff
500	Incident côté Metaventus	Réessayer après quelques secondes ; si le problème persiste, nous contacter

Ce que l'API ne fait pas

Un 404 sur une ressource d'un autre compte est indistinguable d'un 404 sur une ressource inexistante. C'est délibéré : confirmer l'existence d'un identifiant qui ne vous appartient pas serait une fuite d'information.

Un 2xx autre que 200 reste un succès. 201 signale une création, 202 une demande acceptée dont le traitement se poursuit en arrière-plan, 204 une opération réussie sans corps de réponse. Traiter « différent de 200 » comme un échec est l'erreur d'intégration la plus courante.