Foutcodes | LocatieAPI

Overzicht

Alle foutcodes van de API
Status	Titel	Wanneer
400	Request validation failed	De postcode voldoet niet aan het patroon, of het huisnummer is geen geheel getal.
401	Invalid API key	De header X-Api-Key ontbreekt, is onbekend of is ingetrokken.
404	Resource not found	De combinatie bestaat niet in de BAG.
429	Rate limit exceeded	Je zit boven je calls per seconde of boven je maandbundel.

Het formaat

De v3-endpoints geven fouten terug als application/problem+json, precies zoals postcodeapi.nu. Het veld heet title, niet message of error.

400 application/problem+json

{
  "title": "Request validation failed",
  "invalidParams": [
    { "name": "number", "reason": "should be integer" }
  ]
}

De v1-endpoints zijn van onszelf en gebruiken een gewone JSON-vorm met een error-object:

404 application/json

{
  "error": {
    "code": "not_found",
    "message": "Geen adres gevonden voor deze combinatie"
  }
}

De foutteksten van v3 zijn Engels

Dat is met opzet: ze volgen letterlijk de teksten van postcodeapi.nu, zodat code die daarop controleert blijft werken na een overstap. Alles wat op de site en in het dashboard staat is Nederlands.

Afhandelen

400 Een invoerfout van jouw kant. Toon de gebruiker een nette melding en probeer het niet opnieuw met dezelfde waarden. Kijk in invalidParams welk veld het betreft.
401 Een probleem met de sleutel. Opnieuw proberen helpt nooit. Log dit als een fout die iemand moet oplossen en val terug op handmatige invoer.
404 Het adres bestaat niet. Dit is een normaal antwoord, geen storing. Laat de gebruiker zijn adres met de hand invullen.
429 Wachten en opnieuw proberen met exponentiële terugval. Kijk naar X-RateLimit-Reset voor het aantal seconden en naar X-Quota-Remaining om te zien of je bundel op is.
5xx Een storing bij ons. Probeer het maximaal twee keer opnieuw met terugval en val daarna terug op handmatige invoer. Kijk op de statuspagina.

Blokkeer nooit je eigen formulier

Een adresopzoeker is een hulpmiddel, geen voorwaarde. Wat er ook misgaat: laat de velden voor straat en plaats invulbaar, zet een timeout van vijf seconden en laat de gebruiker altijd door kunnen.

Valkuilen

Postcode zonder spatie

De API accepteert 1021JT, niet 1021 JT. Haal de spatie er in je eigen code uit voordat je de URL bouwt.

Huisnummer als geheel getal

In /v3/lookup hoort alleen het cijferdeel. 29a geeft een 400 en geen 404.

Toevoegingen horen bij /v1/addresses

Wil je huisletters en toevoegingen, gebruik dan /v1/addresses met letter en addition.

location is [longitude, latitude]

GeoJSON zet de lengtegraad eerst. Dat is de omgekeerde volgorde van wat de meeste kaartbibliotheken als "lat, lng" tonen.

location kan null zijn

Bij een postbus is er geen coördinaat en is street letterlijk Postbus.

Fouten zijn problem+json

Foutresponses van v3 hebben Content-Type: application/problem+json en een veld title, geen message.