Rate limiting

De Puntjes API kent twee soorten limieten: rate limits (requests per minuut) en planlimieten (wat je abonnement bevat). Alleen het tegoed aan transacties is maandelijks. De rest zijn vaste plafonds die niet herstellen.

---

Rate limits

Elk abonnement bepaalt hoeveel API-requests je per minuut mag doen (rate_limit_per_minute). Ga je erover, dan antwoordt de API:

HTTP 429 Too Many Requests

Elke response draagt X-RateLimit-Limit en X-RateLimit-Remaining. Je leest je limiet dus af zonder ze eerst op te maken.

De teller loopt per handelaar. Het getal van je abonnement is dus je hele limiet: een tweede set credentials levert geen tweede venster op. Een kassa en een webshop op één account putten uit hetzelfde venster, en een integratie die op hol slaat, remt daarmee ook je andere. De teller loopt niet per IP-adres, dus collega's achter dezelfde kantoorverbinding delen nooit een limiet met een andere handelaar.

Geweigerde requests tellen mee

De limiter draait vóór de authenticatie en vóór de accountcontroles. Een request die toch gaat mislukken, kost je er evengoed een. Een verkeerd client secret antwoordt 401, een geschorst account antwoordt 403, en beide zetten dezelfde teller een stap lager als een geslaagde aanroep.

Dat verandert hoe je een nieuwe integratie debugt. Een retry loop met verkeerde credentials komt uit op 429, en die 429 zegt niets over die credentials. Ze betekent alleen dat je te vaak gevraagd hebt. Zet het secret recht, en lees de throttle niet als een tweede aanwijzing.

Requests die bij geen handelaar horen

Horen je credentials bij geen enkel account dat de API mag gebruiken, dan telt de request mee op een aparte en veel kleinere limiet. Die loopt per aanroepend adres in plaats van per handelaar: zonder leesbaar token is er geen handelaar om op te tellen. Drie gevallen komen hier terecht: een ontbrekend of ongeldig bearer token, een client die aan geen handelaar gekoppeld is, en een account waarvan de status toegang weigert.

De limiet van je abonnement blijft daarbij onaangeroerd. De twee tellers staan los van elkaar, dus wie jouw adres met foute tokens afzoekt, kan de requests die jij betaalt niet opmaken.

Rate limits afhandelen

Krijg je een 429 terug:

1. Wacht voor je het opnieuw probeert, met exponential backoff
2. Bekijk de requestpatronen van je integratie
3. Cache responses waar dat zinvol is (bv. de lijst met beloningen of met campagnes)

---

De limieten van je abonnement

Elk abonnement legt deze plafonds vast. Nul betekent onbeperkt, bij alle.

Limiet	Herstelt	Beschrijving
max_transactions	Maandelijks	Transacties per factureringsperiode
max_customers	Nooit	Klanten die de handelaar in totaal mag hebben
max_rewards	Nooit	Actieve beloningen
max_campaigns	Nooit	Campagnes die de handelaar mag hebben
max_locations	Nooit	Vestigingen die de handelaar mag hebben
rate_limit_per_minute	Per minuut	API-requests per minuut

Alleen de transactielimiet herstelt. Een POST /customers die wordt geweigerd omdat de klantenlimiet is bereikt, wordt volgende maand opnieuw geweigerd. De handelaar moet upgraden of een klant verwijderen. Later opnieuw proberen lost het niet op.

Die weigering is een 422 VALIDATION_ERROR, geen 429. De code 429 PLAN_LIMIT_EXCEEDED is voorbehouden aan de transactiemeter, want dat is de enige limiet waarvan de weigering vanzelf verdwijnt.

Overschrijdingsdrempel

Abonnementen bevatten een overschrijdingsdrempel (procentuele buffer). Met een limiet van 1000 transacties en een overschrijdingsdrempel van 10% ligt de harde limiet op 1100 transacties.

Zodra de harde limiet bereikt is, antwoordt de API:

{
    "error": {
        "code": "PLAN_LIMIT_EXCEEDED",
        "message": "Transaction limit exceeded for your subscription plan.",
        "status": 429
    }
}

---

Feature flags

Het abonnement bepaalt ook welke functies je kunt gebruiken:

Mogelijkheid	Beschrijving
Campagnes	Of de handelaar campagnes kan aanmaken en gebruiken
Klantmoment-campagnes	Of die campagnes verjaardags-, jubileum- of win-backcadeaus mogen zijn, of alleen puntenvermenigvuldigers
Puntvervaldatum	Of de handelaar puntvervaldatum kan inschakelen

Zit een functie niet in het abonnement, dan krijg je een fout zodra je ze toch gebruikt.

---

Gebruik controleren

Facturatie in het beheerportaal toont de huidige periode: geregistreerde transacties, het tegoed dat het abonnement bevat, of dat tegoed op is, en de laatste dag van de periode.

De API meldt daar niets van. Er is geen endpoint voor gebruik en geen header met het resterende tegoed, dus een integratie merkt pas dat het tegoed op is aan een 429 PLAN_LIMIT_EXCEEDED op de volgende POST /transactions: een response die binnen de periode niet vanzelf overgaat. Schrijf die vertakking dus alsnog; zie Foutafhandeling.

De meter telt af tegen het aantal dat het abonnement belooft, niet tegen de harde limiet. Een volle meter houdt niets tegen (de overschrijdingsmarge hierboven zegt hoever schrijfacties doorgaan), maar het is wel het punt waar het abonnement stopt met dekken. Daarom markeert de meter het en meldt hij dat het tegoed op is. Hij slaat opnieuw om bij de harde limiet, waar de 429 begint.