Limieten en headers | LocatieAPI

Twee limieten naast elkaar

Rate limit

Het aantal aanroepen per seconde. Die beschermt de API tegen pieken. Loop je eroverheen, dan krijg je een 429 en kun je het een seconde later opnieuw proberen.

Bundel

Het aantal calls per factuurperiode. Die loopt mee met je abonnement en niet met de kalendermaand. Is de bundel op, dan krijg je ook een 429, maar dan tot de volgende periode of tot je opwaardeert.

Sandboxverkeer valt onder geen van beide: dat is gratis en onbeperkt in elk plan.

De headers op elke response

Vaste responseheaders
Header	Betekenis
X-RateLimit-Limit	Het aantal calls per seconde dat bij je plan hoort.
X-RateLimit-Remaining	Wat er in het huidige venster van dat aantal over is.
X-RateLimit-Reset	Aantal seconden tot het venster opnieuw begint.
X-Quota-Limit	De maandbundel van je plan in aantal calls.
X-Quota-Remaining	Wat er van die bundel over is in de lopende factuurperiode.
X-Quota-Reset	Unix-tijdstip waarop de volgende factuurperiode begint.
X-Request-Id	Uniek nummer per verzoek. Noem dit bij een supportvraag.
Cache-Control	Bij een 200: `public, max-age=86400`. Adressen veranderen zelden.

Voorbeeld van een 200

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=86400
X-RateLimit-Limit: 15
X-RateLimit-Remaining: 14
X-RateLimit-Reset: 1
X-Quota-Limit: 20000
X-Quota-Remaining: 18431
X-Quota-Reset: 1788220800
X-Request-Id: d94e20eb-7dd6-45dc-bdfb-e3ab17c72207

Log altijd het X-Request-Id

Elk verzoek krijgt een eigen nummer. Zit je met een antwoord dat je niet verwacht, stuur dat nummer dan mee in je supportvraag; wij kunnen daarmee precies zien wat er gebeurd is.

Limieten per plan

Bundel en snelheid per plan
Plan	Calls per maand	Calls per seconde	Sleutels
Gratis	500	3	2
Starter	1.000	5	2
Klein	5.000	10	5
Standaard	20.000	15	10
Plus	50.000	25	25
Pro	100.000	50	onbeperkt
Enterprise	250.000+	100+	onbeperkt

Coulance en 429

•Betaalde plannen krijgen 10% coulance boven de bundel. Bij 20.000 calls loop je dus tot 22.000 door voordat de API dichtgaat.
•Het gratis plan stopt hard op 500. Dat is bewust: je krijgt nooit een naheffing die je niet zag aankomen.
•Je krijgt een mail bij 80% en bij 100% van je bundel, op het adres van je account.
•Opwaarderen werkt direct. De nieuwe bundel gaat in op het moment dat je wisselt, niet pas volgende maand.

429 application/problem+json

{
  "title": "Rate limit exceeded"
}

Caching scheelt het meeste

Adressen wijzigen zelden. Bij een 200 sturen we daarom Cache-Control: public, max-age=86400 mee. Respecteer die in je eigen laag: een dag cachen op de sleutel postcode plus huisnummer haalt in de praktijk de helft tot driekwart van je calls weg, zeker in een checkout waar mensen heen en weer klikken.

Cache ook de 404, maar korter, bijvoorbeeld een uur. Een adres dat vandaag niet bestaat kan er morgen wel zijn: de data wordt elke werkdag bijgewerkt.