{
"error": {
"code": "plan_required",
"message": "'history' requires the pro plan or above.",
"request_id": "req_0192d3a4b5c67d8e9f0a1b2c3d4e5f65",
"details": {
"capability": "history",
"required_plan": "pro"
},
"required_plan": "pro"
}
}
code est stable et lisible par une machine. message s’adresse à une personne, en anglais, et nomme ce qui n’allait pas : le paramètre, la valeur, ce qui était attendu.request_id figure aussi dans l’en-tête X-Request-Id. Mentionnez-le si vous nous écrivez : c’est l’id dans nos journaux.details est toujours un objet, vide s’il n’y a rien à ajouter. required_plan n’apparaît que sur plan_required.- Un
429 porte Retry-After en secondes.
{
"error": {
"code": "invalid_body",
"message": "company.postcode: company.postcode is not a Belgian postcode",
"request_id": "req_0192d3a4b5c67d8e9f0a1b2c3d4e5f66",
"details": {
"field": "company.postcode"
}
}
}
{
"error": {
"code": "plan_required",
"message": "companies=800 is above the 500 this plan allows. The enterprise plan or above allows it.",
"request_id": "req_0192d3a4b5c67d8e9f0a1b2c3d4e5f67",
"details": {
"capability": "companies_max",
"parameter": "companies",
"requested": "800",
"allowed": "500",
"required_plan": "enterprise"
},
"required_plan": "enterprise"
}
}
400 invalid_parameter signifie que la requête n’a pas pu être lue telle quelle : un paramètre de requête inconnu ou répété, une valeur hors de sa liste, une limite au-delà de votre formule, ou un corps JSON illisible, avec une propriété que la route ne connaît pas ou une valeur du mauvais type. 422 invalid_body signifie que le corps a été lu et contient quelque chose d’impossible : un code postal non belge, un numéro d’entreprise aux chiffres de contrôle faux, un budget négatif. details.field nomme la propriété.
Requête
Erreurs : Requête| Code | Statut | Quand | Que faire |
|---|
| invalid_parameter | 400 | Un paramètre de requête est mal formé, hors limites, répété ou inconnu de la route ; une valeur ne fait pas partie de sa liste ; limit dépasse la taille de page de votre formule ; ou un corps JSON est illisible, contient une propriété que la route ne connaît pas ou une valeur du mauvais type. | Le message nomme le paramètre et ce qui était attendu. Corrigez la requête : la renvoyer telle quelle échoue de la même façon. Les paramètres inconnus sont refusés plutôt qu'ignorés, pour qu'une faute de frappe n'élargisse jamais un résultat à votre insu. |
| invalid_cursor | 400 | Le curseur n'a pas été émis par l'API, ou il l'a été pour une autre liste ou un autre ordre de tri. | Recommencez sans curseur. L'API refuse plutôt que de repartir discrètement de la première page. |
| invalid_body | 422 | Le corps JSON est lisible mais contient quelque chose d'impossible : un numéro d'entreprise dont les chiffres de contrôle sont faux, un code postal non belge, un code NACE invalide, une forme juridique inconnue, un montant négatif, une limite hors bornes, une référence en double.details: field : la propriété en cause, par exemple company.postcode. | Corrigez la propriété indiquée dans details.field. |
| route_not_found | 404 | Aucun endpoint n'existe à ce chemin. La réponse reste du JSON, dans la structure d'erreur habituelle. | Vérifiez le chemin dans /v1/openapi.json. |
| method_not_allowed | 405 | Le chemin existe, mais pas avec cette méthode, par exemple un GET sur /mcp. | L'en-tête Allow liste les méthodes acceptées par ce chemin. |
Clé et formule
Erreurs : Clé et formule| Code | Statut | Quand | Que faire |
|---|
| unauthorized | 401 | La clé est absente, mal formée ou révoquée, sur une route qui en demande une. | Envoyez Authorization: Bearer avec une clé de production ou de test du tableau de bord. |
| subscription_required | 402 | Le compte de la clé n'a pas encore de formule. Il peut se connecter et créer des clés, mais aucune clé ne donne accès aux données tant qu'aucune formule n'est choisie. | Choisissez une formule dans le tableau de bord. La même clé fonctionne dès que la formule est active. |
| plan_required | 403 | La route demande une fonction que votre formule n'inclut pas (le flux de modifications, l'historique, as_of, les webhooks, le matching en masse, les listes de suivi, l'export complet), ou un nombre dépasse ce que votre formule permet (entreprises dans un matching en masse, entreprises sur l'ensemble de vos listes de suivi, endpoints de webhook).details: capability et required_plan pour une fonction manquante ; pour un nombre trop élevé, aussi parameter, requested et allowed. error.required_plan répète la formule. | required_plan est la formule la moins chère qui aurait répondu. Passez à une formule supérieure, ou renoncez à la fonction. |
Données
Erreurs : Données| Code | Statut | Quand | Que faire |
|---|
| subsidy_not_found | 404 | Aucune mesure n'a cet id ou ce slug.details: subsidy : l'id ou le slug demandé. | GET /v1/subsidies les liste. Une mesure fusionnée dans une autre continue de renvoyer vers celle-ci : un ancien id n'explique donc pas cette erreur. |
| version_not_found | 404 | La mesure existe, mais pas la version demandée, ou elle n'existait pas encore à l'instant as_of. | Le message indique la version actuelle, ou la date de la première version. |
| source_not_found | 404 | Aucune source n'a cet id. Aussi renvoyé quand un filtre de webhook nomme une source inconnue.details: source : l'id fourni. | GET /v1/sources les liste. |
| watchlist_not_found | 404 | Aucune liste de suivi avec cet id n'appartient à votre compte. Aussi renvoyé quand un filtre de webhook en nomme une. | GET /v1/watchlists liste les vôtres. |
| webhook_not_found | 404 | Aucun endpoint de webhook avec cet id n'appartient à votre compte. | GET /v1/webhooks liste les vôtres. |
| not_found | 404 | La référence d'entreprise que vous voulez retirer n'est pas sur la liste de suivi. | GET /v1/watchlists/{id}/companies liste les références qu'elle contient. |
| conflict | 409 | La requête est valide mais l'état ne la permet pas, par exemple une 51e liste de suivi sur un même compte. | Le message dit pourquoi. Modifiez d'abord l'état (supprimez une liste), puis réessayez. |
Limites
Erreurs : Limites| Code | Statut | Quand | Que faire |
|---|
| rate_limit_exceeded | 429 | Trop de requêtes par seconde pour votre formule (ou, sur les routes sans clé, pour votre adresse). Aussi renvoyé quand les deux créneaux de téléchargement de l'export complet sont occupés. | Attendez le nombre de secondes indiqué dans Retry-After (1, ou 5 pour l'export). Demandez les pages une à une plutôt qu'en parallèle. |
| quota_exceeded | 429 | Le quota de requêtes du mois est épuisé. | Retry-After compte les secondes jusqu'au début du mois UTC suivant. RateLimit-Remaining permet de le voir venir. |
| match_quota_exceeded | 429 | Les évaluations de matching du mois sont épuisées, ou un matching en masse ou un ajout à une liste de suivi vous ferait dépasser la limite. La lecture des mesures fonctionne toujours.details: limit : les évaluations de matching mensuelles de votre formule. | Retry-After compte les secondes jusqu'au mois UTC suivant. Une formule supérieure en offre davantage. Rien d'une requête en masse refusée n'est évalué ni compté. |
Serveur
Erreurs : Serveur| Code | Statut | Quand | Que faire |
|---|
| internal_error | 500 | Une erreur s'est produite de notre côté. Le détail est journalisé, jamais envoyé. | Réessayez avec un délai croissant. Si l'erreur persiste, envoyez-nous le request_id. |
| billing_unavailable | 503 | Le paiement par carte n'est pas configuré ou le prestataire de paiement n'a pas répondu. Uniquement sur les routes de facturation du tableau de bord. | Réessayez plus tard, ou écrivez-nous. |
| timeout | 504 | La requête a duré plus de 30 secondes et a été interrompue. Aucune route ne devrait en approcher ; l'export est diffusé en flux. | Réessayez. Un filtre plus étroit ou une page plus petite répond plus vite. |
Connexion au tableau de bord
Erreurs : Connexion au tableau de bord| Code | Statut | Quand | Que faire |
|---|
| google_sign_in_failed | 401 | Un jeton de connexion Google n'a pas pu être vérifié. | Reconnectez-vous. |
| password_sign_in_disabled | 403 | Une inscription ou une connexion par mot de passe a été tentée alors que seule la connexion Google est proposée. | Connectez-vous avec Google. |
- Les corps de requête sont limités à 2 Mo.
- Après l’authentification, l’endpoint MCP répond aux problèmes de protocole par des erreurs JSON-RPC (HTTP
200, ou 400 pour un corps qui n’est pas du JSON), et à un outil en échec par un résultat avec isError ; voir MCP.
Réessayer
Réessayez un 429 après Retry-After, et les 500, 503 et 504 avec un délai exponentiel. Ne renvoyez pas tels quels les 400, 401, 402, 403, 404 ou 422 : la même requête échoue de la même façon.
