De foutstructuur

json

{
  "error": {
    "code": "validation_failed",
    "message": "The request contains invalid fields.",
    "details": [
      {
        "field": "type",
        "code": "invalid_value",
        "message": "Must be one of: company, private."
      }
    ]
  }
}

code is stabiel en bedoeld voor je code: daar schakel je op. message is bedoeld voor mensen en kan veranderen. details verschijnt bij validatiefouten en wijst per veld aan wat er mis is. Optioneel kan request_id meegestuurd worden.

HTTP-statuscodes

Status	Betekenis
200	Gelukt
201	Aangemaakt
204	Verwijderd of succes zonder inhoud (o.a. product delete)
401	Geen of ongeldige API-key
403	Key mist de benodigde scope of module-toegang
404	Object bestaat niet of hoort niet bij jouw omgeving
409	Conflict (bijv. actor of module-voorwaarde)
422	Validatiefout, verkeerd Content-Type of ongeldige JSON
429	Te veel requests, zie Rate limits
500	Fout aan onze kant. Probeer het later opnieuw

Error-codes

Veelvoorkomende codes:

Code	Uitleg
`validation_failed`	Validatie mislukt; zie `details` per veld
`invalid_content_type`	Content-Type is niet `application/json` waar dat verplicht is
`not_found` / `*_not_found`	Resource niet gevonden
`rate_limited`	Rate limit overschreden (`429`)
`actor_required`	Conflict: actor ontbreekt waar die verplicht is
`online_payments_disabled`	Conflict: online betalingen staan uit
`incasso_disabled`	Conflict: incasso staat uit
`mandate_already_verified`	Conflict: mandaat is al geverifieerd

Zo ga je met fouten om

Schakel op error.code, nooit op message.
Toon bij een 422 de details aan je gebruiker: die zijn er precies voor.
Bij een 500 of timeout: probeer opnieuw met dezelfde Idempotency-Key.