Rate Limiting

De Avallo REST API beperkt het aantal requests om de beschikbaarheid van de dienst te beschermen en te voorkomen dat een foutieve integratie onbedoeld te veel capaciteit gebruikt.

Gepubliceerde limieten

Voor geauthenticeerde groundwater-requests geldt per API-client:

Limiet	Waarde
Doorlopende limiet	30 requests per minuut
Burstcapaciteit	60 requests
Gelijktijdige requests	maximaal 2

De burstcapaciteit maakt een korte piek mogelijk. Daarna wordt capaciteit opnieuw beschikbaar volgens de doorlopende limiet.

Wanneer meer dan twee requests gelijktijdig worden uitgevoerd, kan een request direct worden geweigerd. Clients moeten daarom hun parallelisme begrenzen.

Te veel requests

Wanneer de verzoeklimiet wordt overschreden, retourneert de API:

429 Too Many Requests

De foutresponse gebruikt:

application/problem+json

Waar mogelijk bevat de response daarnaast:

Retry-After: {seconds}

Gebruik Retry-After om te bepalen wanneer een volgend request kan worden uitgevoerd.

Opnieuw proberen

Voer hetzelfde request na een 429 niet onmiddellijk opnieuw uit.

Wacht minimaal gedurende de periode uit Retry-After. Wanneer opnieuw een 429 wordt ontvangen, vergroot dan de wachttijd. Automatische retries moeten altijd worden begrensd door een maximumaantal pogingen of een totale time-out.

Voeg bij meerdere gelijktijdige workers een kleine willekeurige afwijking aan de wachttijd toe, zodat zij niet allemaal op hetzelfde moment opnieuw proberen.

De huidige publieke endpoints gebruiken GET en kunnen veilig opnieuw worden uitgevoerd.

Requests efficiënt uitvoeren

Vraag alleen het tijdsinterval op dat nodig is:

curl --request GET \
   --url "https://api.avallo.nl/v1/groundwater-monitoring-tubes/{tubeIdentifier}/measurements?from=2026-09-01T00%3A00%3A00Z&to=2026-09-08T00%3A00%3A00Z" \
   --header "Accept: application/json" \
   --header "X-API-Key: {apiKey}"

Bewaar waar passend welk tijdsinterval al is verwerkt, zodat dezelfde gegevens niet onnodig opnieuw worden opgehaald.

Structurele beperkingen

Neem contact op met Avallo wanneer een noodzakelijke integratie structureel 429-responses ontvangt. Vermeld daarbij het endpoint, het geschatte requestvolume en de momenten waarop de beperking optreedt.

Deel nooit de API-key.

Zie Error Handling voor de verwerking van andere foutstatuscodes.