Wat zijn de limieten en foutmeldingen van de API?

Hoeveel aanvragen mag je doen?

De API beperkt het aantal aanvragen per minuut per account.

Ga je eroverheen, dan krijg je een 429 met een header die vertelt hoelang je moet wachten:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": {
    "type": "invalid_request",
    "message": "Rate limit exceeded, try again after 60 seconds"
  }
}

Er zijn geen headers die je verbruik bijhouden zolang het goed gaat. Wacht dus op de Retry-After en houd zelf bij hoeveel aanvragen je verstuurt. Cache daarnaast wat zelden verandert: de velden van een lijst hoef je niet bij elke paginaweergave op te halen, één keer per dag is genoeg.

Hoe ziet een foutmelding eruit?

Alle foutmeldingen hebben dezelfde opbouw, dus je kunt ze op één plek afvangen. Elke fout komt terug als JSON met een type, een message, en meestal een code en de parameter die de fout veroorzaakte.

{
  "error": {
    "type": "invalid_input",
    "message": "Email: invalid address",
    "code": 208,
    "parameter": "email"
  }
}

Het veld type kan drie waarden hebben: invalid_request als de aanroep zelf niet klopt, invalid_input als de meegestuurde gegevens niet kloppen, en internal als het aan de kant van Laposta misgaat.

Statuscodes

De API gebruikt gewone HTTP-statuscodes om aan te geven hoe de aanvraag is verlopen.

Foutcodes

Bij invalid_input staat een numerieke code, zodat je de fout kunt vertalen naar een melding voor je eigen gebruiker. Samen met parameter weet je precies om welk veld het gaat.

Een id van een ander account geeft dezelfde melding als een id dat nergens bestaat: Unknown list, met code 203. Dat is met opzet, zodat niet te zien is wat er in andere accounts staat.

Gerelateerde artikelen