API REST / Codes d'erreur

Codes d'erreur

Référence complète des erreurs HTTP retournées par l'API REST Normi.

Format de réponse

Toutes les erreurs retournent un objet JSON avec un champ error structuré :

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits. You have 3 credits, this tool costs 5."
  }
}

MCP vs REST

En REST, les erreurs sont signalées par le code HTTP (402, 429, etc.) et le corps JSON ci-dessus. En MCP, la plupart des erreurs (crédits insuffisants, capacité) sont retournées comme texte dans content[0].text — pas comme erreur HTTP. Seuls 401, 409 et 429 sont des erreurs HTTP côté MCP.

Tableau de référence

HTTP	`code`	Cause
400	`invalid_params`	Validation Zod échouée — paramètre manquant, type incorrect ou valeur hors plage.
400	`missing_location`	Aucun filtre de localisation fourni (code_postal, commune, code_departement ou lat+lon).
401	`missing_bearer_token`	Aucun header X-API-Key ni Authorization: Bearer présent dans la requête.
401	`unknown_key`	Le token n'existe pas dans la base de données (hash SHA-256 introuvable).
401	`inactive_key`	Le token a été révoqué (is_active = false). Créez un nouveau token dans le dashboard.
402	`insufficient_credits`	Solde de crédits insuffisant pour exécuter la requête. Rechargez votre compte.
403	`plan_required`	Fonctionnalité réservée aux plans Pro/Enterprise (ex. alertes webhook).
404	`not_found`	Ressource introuvable (transaction, alerte, bien du portefeuille). Les crédits sont remboursés automatiquement sur les endpoints directs (:id).
429	`rate_limited`	Limite de débit dépassée pour votre plan. Voir la page Limites de débit pour les seuils par plan.
503	`at_capacity`	Le serveur a atteint sa limite de 15 requêtes DB simultanées. Réessayez après quelques secondes.
503	`service_unavailable`	La base de données n'est pas configurée (variable d'environnement manquante). Erreur d'infrastructure.
500	`query_failed`	La requête SQL a levé une exception inattendue.

Recommandations client

401 : ne réessayez pas automatiquement — le token est invalide ou révoqué. Affichez une erreur à l'utilisateur.
402 : vérifiez le solde avant d'appeler des endpoints coûteux. Le champ _credits.remaining est inclus dans chaque réponse réussie.
429 : implémentez un backoff exponentiel (1s, 2s, 4s). La limite est une fenêtre glissante de 60 secondes.
503 at_capacity : le serveur est saturé (15 requêtes DB simultanées). Réessayez après 2–5 secondes avec backoff.
404 sur :id : les crédits sont automatiquement remboursés sur GET /v1/transactions/:id et GET /v1/businesses/:siren quand la ressource est introuvable.

Détecter la limitation automatique

Une requête réussie (HTTP 200) peut contenir un champ notice indiquant qu'un filtre de date a été appliqué automatiquement (ex. rayon > 1000 m → 12 derniers mois). Ce n'est pas une erreur, mais cela signifie que les résultats sont restreints. En savoir plus sur les filtres automatiques.

API BDNB — Bâtiments CSTB

Playground interactif