{
"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 is stabiel en machineleesbaar. message is voor een mens, in het Engels, en zegt wat er fout was: de parameter, de waarde, wat er verwacht werd.request_id staat ook in de header X-Request-Id. Vermeld hem als je ons schrijft: het is het id in onze logs.details is altijd een object, leeg als er niets toe te voegen is. required_plan verschijnt alleen bij plan_required.- Een
429 bevat Retry-After in seconden.
{
"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 betekent dat de request niet gelezen kon worden zoals gevraagd: een onbekende of herhaalde queryparameter, een waarde buiten haar waardenlijst, een limit boven je plan, of een JSON-body die niet te parsen is, een eigenschap bevat die de route niet kent of een waarde van het verkeerde type. 422 invalid_body betekent dat de body gelezen werd en iets zegt dat niet kan kloppen: een postcode die niet Belgisch is, een ondernemingsnummer met foute controlecijfers, een negatief budget. details.field noemt de eigenschap.
Request
Fouten: Request| Code | Status | Wanneer | Wat te doen |
|---|
| invalid_parameter | 400 | Een queryparameter is misvormd, valt buiten het bereik, komt twee keer voor of bestaat niet op deze route; een waarde hoort niet bij haar vaste waardenlijst; een limit ligt boven de paginagrootte van je plan; of een JSON-body is niet te parsen, bevat een eigenschap die de route niet kent of een waarde van het verkeerde type. | De melding noemt de parameter en wat er verwacht werd. Pas de request aan: ongewijzigd opnieuw proberen mislukt op dezelfde manier. Onbekende parameters worden geweigerd in plaats van genegeerd, zodat een tikfout een resultaat nooit ongemerkt ruimer maakt. |
| invalid_cursor | 400 | De cursor komt niet van de API, of hoort bij een andere lijst of sorteervolgorde. | Begin opnieuw zonder cursor. De API weigert liever dan stilzwijgend weer bij pagina één te beginnen. |
| invalid_body | 422 | De JSON-body is leesbaar maar zegt iets onmogelijks: een ondernemingsnummer waarvan de controlecijfers niet kloppen, een postcode die niet Belgisch is, een ongeldige NACE-code, een onbekende rechtsvorm, een negatief bedrag, een limit buiten het bereik, een dubbele referentie.details: field: de eigenschap in kwestie, bijvoorbeeld company.postcode. | Verbeter de eigenschap die details.field noemt. |
| route_not_found | 404 | Op dit pad bestaat geen endpoint. Het antwoord is toch JSON, in de gewone foutstructuur. | Vergelijk het pad met /v1/openapi.json. |
| method_not_allowed | 405 | Het pad bestaat, maar niet met deze methode, bijvoorbeeld een GET op /mcp. | De header Allow somt de methodes op die het pad wel aanvaardt. |
Sleutel en plan
Fouten: Sleutel en plan| Code | Status | Wanneer | Wat te doen |
|---|
| unauthorized | 401 | De sleutel ontbreekt, is misvormd of ingetrokken, op een route die er een vraagt. | Stuur Authorization: Bearer mee met een live- of testsleutel uit het dashboard. |
| subscription_required | 402 | Het account van de sleutel heeft nog geen plan. Je kunt aanmelden en sleutels aanmaken, maar geen enkele sleutel geeft gegevens tot er een plan gekozen is. | Kies een plan in het dashboard. Dezelfde sleutel werkt zodra het plan actief is. |
| plan_required | 403 | De route vraagt een functie die je plan niet bevat (de change feed, historiek, as_of, webhooks, bulkmatching, watchlists, de volledige export), of een aantal ligt boven wat je plan toelaat (ondernemingen in een bulkmatch, ondernemingen over al je watchlists, webhook-endpoints).details: capability en required_plan bij een ontbrekende functie; bij een aantal boven het plan ook parameter, requested en allowed. error.required_plan herhaalt het plan. | required_plan is het goedkoopste plan dat wel geantwoord had. Stap over naar een hoger plan, of laat de functie weg. |
Gegevens
Fouten: Gegevens| Code | Status | Wanneer | Wat te doen |
|---|
| subsidy_not_found | 404 | Geen enkele maatregel heeft dit id of deze slug.details: subsidy: het id of de slug die je vroeg. | GET /v1/subsidies geeft de lijst. Een maatregel die in een andere opging, blijft naar die andere verwijzen, dus een oud id is hier geen oorzaak van. |
| version_not_found | 404 | De maatregel bestaat, maar niet de gevraagde versie, of hij bestond nog niet op het as_of-tijdstip. | De melding zegt welke versie actueel is, of van wanneer de eerste versie dateert. |
| source_not_found | 404 | Geen enkele bron heeft dit id. Ook het antwoord wanneer een webhookfilter een onbekende bron noemt.details: source: het id dat je gaf. | GET /v1/sources geeft de lijst. |
| watchlist_not_found | 404 | Geen watchlist met dit id hoort bij je account. Ook het antwoord wanneer een webhookfilter er zo een noemt. | GET /v1/watchlists geeft de jouwe. |
| webhook_not_found | 404 | Geen webhook-endpoint met dit id hoort bij je account. | GET /v1/webhooks geeft de jouwe. |
| not_found | 404 | De referentie van de onderneming die je wilt verwijderen, staat niet op de watchlist. | GET /v1/watchlists/{id}/companies geeft de referenties die erop staan. |
| conflict | 409 | De request is geldig, maar de toestand laat hem niet toe, bijvoorbeeld een 51e watchlist op één account. | De melding zegt waarom. Pas eerst de toestand aan (verwijder een watchlist) en probeer dan opnieuw. |
Limieten
Fouten: Limieten| Code | Status | Wanneer | Wat te doen |
|---|
| rate_limit_exceeded | 429 | Te veel requests per seconde voor je plan (of, op de routes zonder sleutel, voor je adres). Ook het antwoord wanneer beide downloadplaatsen voor de volledige export in gebruik zijn. | Wacht het aantal seconden uit Retry-After (1, of 5 voor de export). Vraag pagina's één voor één op in plaats van parallel. |
| quota_exceeded | 429 | Het requestquotum van deze maand is op. | Retry-After telt de seconden tot het begin van de volgende UTC-maand. Met RateLimit-Remaining zie je het aankomen. |
| match_quota_exceeded | 429 | De match-evaluaties van deze maand zijn op, of een bulkmatch of watchlist-upload zou je erover brengen. Maatregelen lezen werkt nog.details: limit: de maandelijkse match-evaluaties van je plan. | Retry-After telt de seconden tot de volgende UTC-maand. Een groter plan heeft er meer. Van een geweigerde bulkrequest wordt niets geëvalueerd of geteld. |
Server
Fouten: Server| Code | Status | Wanneer | Wat te doen |
|---|
| internal_error | 500 | Er liep iets mis aan onze kant. Het detail wordt gelogd, nooit meegestuurd. | Probeer opnieuw met backoff. Blijft het gebeuren, stuur ons dan de request_id. |
| billing_unavailable | 503 | Kaartbetaling is niet ingesteld of de betaalprovider antwoordde niet. Komt alleen voor op de facturatieroutes van het dashboard. | Probeer later opnieuw, of schrijf ons. |
| timeout | 504 | De request duurde langer dan 30 seconden en werd afgebroken. Geen enkele route hoort daar in de buurt te komen; de export wordt gestreamd. | Probeer opnieuw. Een smallere filter of een kleinere pagina antwoordt sneller. |
Aanmelden op het dashboard
Fouten: Aanmelden op het dashboard| Code | Status | Wanneer | Wat te doen |
|---|
| google_sign_in_failed | 401 | Een Google-aanmeldtoken kon niet worden geverifieerd. | Meld je opnieuw aan. |
| password_sign_in_disabled | 403 | Er werd geprobeerd te registreren of aan te melden met een wachtwoord, terwijl alleen aanmelden met Google aangeboden wordt. | Meld je aan met Google. |
- Request-bodies zijn beperkt tot 2 MB.
- Na de authenticatie beantwoordt het MCP-endpoint protocolproblemen als JSON-RPC-fouten (HTTP
200, of 400 voor een body die geen JSON is), en een mislukte tool als resultaat met isError; zie MCP.
Opnieuw proberen
Probeer een 429 opnieuw na Retry-After, en 500, 503 en 504 met exponentiële backoff. Probeer 400, 401, 402, 403, 404 of 422 niet ongewijzigd opnieuw: dezelfde request mislukt op dezelfde manier.
