Documentatie

Foutcodes

Welke statuscodes de API teruggeeft, hoe de foutbody eruitziet en wat je er in je code mee doet.

# LocatieAPI, foutcodes Bron: https://locatieapi.nl/documentatie/foutcodes ## Foutcodes ### v3, application/problem+json | Status | Titel | Wanneer | Body | |---|---|---|---| | 400 | Request validation failed | De postcode voldoet niet aan het patroon, of het huisnummer is geen geheel getal. | `{"title":"Request validation failed","invalidParams":[{"name":"number","reason":"should be integer"}]}` | | 401 | Invalid API key | De header X-Api-Key ontbreekt, is onbekend of is ingetrokken. | `{"title":"Invalid API key"}` | | 404 | Resource not found | De combinatie bestaat niet. | `{"title":"Resource not found"}` | | 429 | Rate limit exceeded | Je zit boven je calls per seconde of boven je maandbundel. | `{"title":"Rate limit exceeded"}` | ### v1, application/json Vorm: `{"error":{"code":"...","message":"..."}}`. Controleer op `error.code`, niet op de melding. | Code | Status | Waar | Voorbeeldmelding | |---|---|---|---| | `invalid_postcode` | 400 | /v1/addresses, /v1/postcodes, /v1/bulk/lookup | Geef een geldige postcode op, bijvoorbeeld 6545CA. | | `invalid_number` | 400 | /v1/addresses, /v1/validate, /v1/bulk/lookup | Het huisnummer moet een geheel getal zijn. | | `invalid_query` | 400 | /v1/autocomplete | Geef minimaal twee tekens op in q. | | `invalid_type` | 400 | /v1/autocomplete | type moet een van deze waarden zijn: all, address, street, city. | | `invalid_coordinates` | 400 | /v1/reverse | Geef lat en lon op als decimale graden. | | `invalid_payload` | 400 | /v1/bulk/lookup | Stuur een lijst addresses met paren van postcode en number. | | `invalid_api_key` | 401 | alle endpoints | Invalid API key | | `plan_upgrade_required` | 403 | /v1/bulk/lookup en andere endpoints buiten je plan | Bulk zit niet in dit plan. | | `not_found` | 404 | /v1/postcodes, onbekende paden, en per regel in /v1/bulk/lookup | Deze postcode is niet bekend. | | `too_many_items` | 422 | /v1/bulk/lookup | Een bulkverzoek bevat maximaal 250 regels, dit verzoek heeft er 400. | | `rate_limit_exceeded` | 429 | alle endpoints | Je gaat over je calls per seconde. | | `quota_exceeded` | 429 | alle endpoints | Je maandbundel is op. | ## 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`. - **v1 zit in een envelope** De v1-endpoints geven `{"data": ...}` terug, met daarnaast een `meta`-object. v3 geeft het adres kaal terug, zonder envelope. - **Twee foutvormen** v3 geeft `application/problem+json` met een veld `title`. v1 geeft gewone JSON met `{"error":{"code","message"}}`; controleer daar op `error.code`, niet op de melding.

Statuscodes van v3

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.
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. 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. De melding is daar Nederlands.

400 application/json

{
  "error": {
    "code": "invalid_postcode",
    "message": "Geef een geldige postcode op, bijvoorbeeld 6545CA."
  }
}

Controleer in je code op error.code, niet op de melding: de code ligt vast, de tekst kan wijzigen.

Alle foutcodes van de v1-endpoints
Code	Status	Waar	Voorbeeldmelding
invalid_postcode	400	/v1/addresses, /v1/postcodes, /v1/bulk/lookup	Geef een geldige postcode op, bijvoorbeeld 6545CA.
invalid_number	400	/v1/addresses, /v1/validate, /v1/bulk/lookup	Het huisnummer moet een geheel getal zijn.
invalid_query	400	/v1/autocomplete	Geef minimaal twee tekens op in q.
invalid_type	400	/v1/autocomplete	type moet een van deze waarden zijn: all, address, street, city.
invalid_coordinates	400	/v1/reverse	Geef lat en lon op als decimale graden.
invalid_payload	400	/v1/bulk/lookup	Stuur een lijst addresses met paren van postcode en number.
invalid_api_key	401	alle endpoints	Invalid API key
plan_upgrade_required	403	/v1/bulk/lookup en andere endpoints buiten je plan	Bulk zit niet in dit plan.
not_found	404	/v1/postcodes, onbekende paden, en per regel in /v1/bulk/lookup	Deze postcode is niet bekend.
too_many_items	422	/v1/bulk/lookup	Een bulkverzoek bevat maximaal 250 regels, dit verzoek heeft er 400.
rate_limit_exceeded	429	alle endpoints	Je gaat over je calls per seconde.
quota_exceeded	429	alle endpoints	Je maandbundel is op.

De foutteksten van v3 zijn Engels

Ze volgen letterlijk het bestaande contract, zodat code die daarop controleert blijft werken na een overstap. Alles op de site en in het dashboard 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.

v1 zit in een envelope

De v1-endpoints geven {"data": ...} terug, met daarnaast een meta-object. v3 geeft het adres kaal terug, zonder envelope.

Twee foutvormen

v3 geeft application/problem+json met een veld title. v1 geeft gewone JSON met {"error":{"code","message"}}; controleer daar op error.code, niet op de melding.