Afspraken

Fouten en statuscodes

Elke fout heeft dezelfde vorm, bij elke status. Reageer op error.code, niet op de HTTP-status alleen en nooit op de tekst: die kan veranderen.

De vorm

Naam	Type	Standaard	Uitleg
`error.code` verplicht	`unauthorized \| forbidden \| not_found \| invalid_request \| method_not_allowed \| conflict \| rate_limited \| internal`	-	Stable machine code. Switch on this, never on the message.
`error.message` verplicht	`string`	-	Human readable explanation in English. May be reworded at any time.
`error.details` optioneel	`object`	-	Extra context. For invalid_request this carries `params`, one entry per bad parameter.
`request_id` verplicht	`string`	-	The X-Request-Id of this response. Quote it when you report a problem.

400 invalid_request

{
  "error": {
    "code": "invalid_request",
    "message": "1 parameter is wrong: limit.",
    "details": {
      "params": [
        {
          "param": "limit",
          "message": "must be 100 or less"
        }
      ]
    }
  },
  "request_id": "9f1c2b4a-7e3d-4a10-9c2f-6b8d1e5a0c33"
}

De codes

Dit zijn alle waarden van error.code. Een nieuwe code is een wijziging van de specificatie en komt in de wijzigingen.

error.code	HTTP	Betekenis
`unauthorized`	`401`	Geen token, een onbekend token of een ingetrokken token.
`forbidden`	`403`	Een geldig token dat dit niet mag: een recht ontbreekt, de organisatie is geschorst, of het gaat om het event van een ander.
`not_found`	`404`	Het endpoint bestaat, maar wat je vraagt niet.
`invalid_request`	`400`	Het verzoek klopt niet: een onbekende waarde, een slechte cursor, een body die geen JSON is.
`method_not_allowed`	`405`	Het pad bestaat, maar niet met deze methode. `Allow` zegt welke wel.
`conflict`	`409`	Het verzoek past niet bij de toestand van wat het raakt.
`rate_limited`	`429`	Over de limiet per minuut of het dagbudget. `Retry-After` zegt hoe lang je wacht.
`internal`	`500`	Onze fout. Het `request_id` is wat wij nodig hebben om het terug te vinden.

Bij invalid_request staat in error.details.params elke parameter die niet klopt, met de reden, in één keer.

Alle statussen in de specificatie

Per endpoint staat in de referentie welke van deze statussen het kan geven.

Status	Betekenis
`400`	The request is wrong. `error.details.params` names every bad parameter.
`401`	No token, or a token we do not know.
`403`	The token is valid but does not carry the `read` scope, or the organisation is suspended.
`404`	No such resource.
`409`	This event does not use external ticketing.
`429`	Over the per-minute limit or the daily quota. `Retry-After` says how long to wait.
`500`	Something went wrong on our side. Quote `request_id`.

Een fout melden

Elk antwoord, goed of fout, heeft een header X-Request-Id, en een fout heeft hem ook in de body als request_id. Stuur die mee als je ons mailt; dan vinden we het verzoek terug. Zie Support.

Bijgewerkt 2026-10-17