Fouten

Elke fout-response is een JSON-object met minstens een error-veld dat beschrijft wat er misging. Statuscodes volgen strikt de HTTP-conventies.

Vorm

{
  "error": "Mensleesbare beschrijving."
}

Sommige fouten dragen extra velden. Quotum-fouten bevatten limit en tier:

{
  "error": "Monthly quota exceeded.",
  "limit": 1000,
  "tier": "FREE"
}

Veld	Type	Beschrijving
200	OK	Succesvolle response.
400	Bad Request	Onjuiste parameters — meestal een ongeldige vervaldatum op key-aanmaken of een onjuiste signup-payload.
401	Unauthorized	Ontbrekende sleutel, ongeldige sleutel, verlopen sleutel of niet-bevestigde e-mail. De error-string onderscheidt de gevallen.
403	Forbidden	Geschorste account of nog niet bevestigde e-mail.
404	Not Found	Geen product met die EAN. Alleen door het lookup-endpoint teruggegeven.
429	Too Many Requests	Maandquotum, per-minuut rate limit of authenticatiepoging-throttle overschreden. Bevat Retry-After bij per-minuut-hits.
500	Server Error	Onverwachte fout aan onze kant. Veilig om opnieuw te proberen met exponentiële back-off.

Veld	Type	Beschrijving
"Missing API key…"	401	Geen Authorization-header en geen X-API-Key-header.
"Invalid API key."	401	Header aanwezig, maar sleutel nooit uitgegeven, ingetrokken of matcht niet.
"API key expired."	401	Je hebt een vervaldatum gezet op deze sleutel en die datum is voorbij. Maak een nieuwe.
"Email not verified."	403	Account bestaat maar de bevestigingslink is nooit aangeklikt.
"Account suspended."	403	Account is handmatig geschorst. Neem contact op met support.
"Product not found"	404	Geen EAN-match. Let op: we valideren geen checksum-cijfers — geef precies door wat op de verpakking staat.
"Monthly quota exceeded."	429	Je hebt je volledige plan-quotum voor de kalendermaand gebruikt. Upgrade of wacht op reset.
"Per-minute rate limit exceeded."	429	Burst-rate te hoog. Honoreer Retry-After en vertraag.
"Too many unauthenticated API requests…"	429	Te veel requests zonder sleutel vanaf dezelfde client. Stuur een geldige sleutel mee of probeer later opnieuw.
"Too many invalid API key attempts…"	429	Te veel ongeldige sleutelpogingen vanaf dezelfde client. Controleer je configuratie en probeer later opnieuw.

4xx-fouten: niet opnieuw proberen zonder de request te wijzigen. Ze blijven falen.
429 per-minuut: wacht op Retry-After, probeer dan opnieuw.
429 maand: niet opnieuw proberen. Upgrade of wacht op kalender-reset.
5xx: probeer opnieuw met exponentiële back-off (bv. 1s, 2s, 4s, tot ~30s). Stop na een paar pogingen en signaleer de fout.