Foutafhandeling

De API retourneert consistente foutresponses. Leer hoe u deze correct afhandelt.

// ERROR_FORMATFoutformaat

FoutformaatAlle fouten volgen hetzelfde JSON-formaat

Foutresponses bevatten altijd een message veld en kunnen aanvullende details bevatten.

Validatiefout (422)

{
  "error": {
    "code": "validation_error",
    "message": "The postcode field format is invalid.",
    "status": 422,
    "errors": {
      "postcode": [
        "The postcode format is invalid. Use format: 1234AB"
      ]
    }
  }
}

Niet gevonden (404)

{
  "error": {
    "code": "address_not_found",
    "message": "No address found for the given postcode and house number.",
    "status": 404
  }
}

Authenticatiefouten (HTTP 401)

{
  "error": {
    "code": "unauthenticated",
    "message": "Unauthenticated.",
    "status": 401
  }
}

Authenticatie- en autorisatiefouten gebruiken dezelfde { error: { code, message, status } } envelope als domeinfouten. Validatiefouten behouden de { message, errors } vorm zodat bestaande clientbibliotheken blijven werken.

// HTTP_CODESHTTP Statuscodes

HTTP StatuscodesOverzicht van alle gebruikte statuscodes

Code	Naam	Beschrijving	Oplossing
400	Bad Request	Het verzoek bevat ongeldige of ontbrekende parameters	Controleer de parameters en hun formaat
401	Unauthorized	Authenticatie vereist of ongeldig token	Voeg een geldige Bearer token toe aan de Authorization header
403	Forbidden	Geen toegang tot deze resource	Controleer uw IP-whitelist, domein-whitelist of accountrechten
404	Not Found	De gevraagde resource bestaat niet	Controleer of de resource bestaat
405	Method Not Allowed	Deze HTTP-methode wordt niet ondersteund voor dit endpoint	Raadpleeg de documentatie voor ondersteunde HTTP-methoden op dit endpoint
408	Request Timeout	De server heeft te lang gewacht op het verzoek	Probeer het verzoek opnieuw; overweeg de scope te verkleinen
422	Validation Error	Validatie mislukt voor de gegeven parameters	Corrigeer de validatiefouten in uw verzoek
429	Too Many Requests	Te veel verzoeken, rate limit bereikt	Wacht tot de Retry-After periode voorbij is
500	Internal Server Error	Interne serverfout	Probeer later opnieuw, neem contact op bij aanhoudende fouten
503	Service Unavailable	Service tijdelijk niet beschikbaar	Wacht tot de service weer beschikbaar is

// APP_CODESApplicatiefoutcodes

ApplicatiefoutcodesSpecifieke foutcodes voor domeinlogica

Code	Beschrijving
unauthenticated	Authenticatie is vereist; geef een geldig Bearer token mee in de Authorization header
unauthorized	Authenticatie is mislukt (meestal door een ongeldig of verlopen token)
forbidden	Het geauthenticeerde account heeft geen rechten om deze actie uit te voeren
token_revoked	De API-sleutel is ingetrokken door de eigenaar of een beheerder
token_expired	De API-sleutel is voorbij de vervaldatum
ip_not_allowed	Het IP-adres van het verzoek staat niet op de IP-whitelist van de sleutel
domain_not_allowed	Het domein van het verzoek staat niet op de domein-whitelist van de browsersleutel
origin_required	Browsersleutels vereisen een Origin-header op het verzoek
browser_key_read_only	Browsersleutels ondersteunen alleen lees-verzoeken (GET)
bad_request	Het verzoek is ongeldig of mist verplichte velden
validation_error	Een of meer parameters zijn ongeldig; per-veld details onder error.errors
invalid_postcode	Ongeldige postcode-indeling (verwacht formaat: 1234AB)
invalid_file	Het opgegeven bestand is ongeldig (grootte, formaat of inhoud)
bbox_too_large	De opgegeven bounding box is groter dan toegestaan (~0,5° vierkant / een grote stad). Beperk de zoekopdracht en probeer opnieuw
method_not_allowed	Deze HTTP-methode wordt niet ondersteund voor dit endpoint
request_timeout	De server heeft te lang gewacht op het verzoek
not_found	De gevraagde resource is niet gevonden (geldt voor gebouwen, steden, straten, gemeenten, provincies en verblijfsobjecten)
address_not_found	Geen adres gevonden voor de gegeven postcode en huisnummer
file_not_found	Het exportbestand is verlopen of niet gevonden op de server
not_ready	De gevraagde export is nog niet voltooid; probeer het later opnieuw
too_many_requests	Rate limit per minuut overschreden; wacht en probeer opnieuw
quota_exceeded	Maandelijks API-quotum is overschreden voor deze sleutel
server_error	Er is een onverwachte fout opgetreden; het verzoek mag na korte vertraging opnieuw geprobeerd worden
service_unavailable	De dienst is tijdelijk niet beschikbaar; probeer opnieuw na de Retry-After vertraging

// BEST_PRACTICESBest Practices

Best PracticesTips voor robuuste foutafhandeling

1. Controleer altijd de HTTP-statuscode voor het parsen van de response
2. Implementeer exponential backoff bij 429-fouten
3. Log foutresponses voor debugging
4. Gebruik de foutcode voor specifieke afhandeling
5. Monitor uw quotumgebruik via de dashboard

Rate Limiting & Quota Headers

Bij 429-responses geven twee response-headers aan wanneer u opnieuw mag proberen:

Retry-After — Aantal seconden te wachten voordat het verzoek opnieuw verstuurd wordt. Aanwezig bij iedere 429-response.
X-Quota-Reset — Unix-timestamp (UTC, seconden) waarop het maandelijkse quota-venster reset. Aanwezig bij quota_exceeded-responses; gebruik Retry-After voor too_many_requests.