Fouten & retries

Fouten worden geretourneerd als JSON met een stabiele, machineleesbare error-code en de bijbehorende HTTP-status.

{
  "error": "rate_limited",
  "message": "Too many requests.",
  "retry_after_ms": 850
}

Foutcodes

HTTP	error	Retry?	Opmerkingen
400	invalid_request	Nee	Een parameter is niet gevalideerd — corrigeer het verzoek.
401	missing_api_key / unknown_api_key	Nee	Zie Authenticatie.
403	inactive_api_key / account_blocked	Nee	Sleutel uitgeschakeld of account geschorst.
402	insufficient_credits	Nee	Vul aan. Body bevat required en balance.
429	rate_limited	Ja, na retry_after_ms	Je hebt je limiet per minuut overschreden.
409	request_in_progress	Ja	Een identiek idempotent verzoek loopt nog.
422	(idempotentieconflict)	Nee	Een Idempotency-Key is hergebruikt met een andere body.
503	service_temporarily_unavailable / too_many_concurrent_requests	Ja, met backoff	Tijdelijke capaciteitslimiet.
504	result_timeout	Ja	De upstream-fetch overschreed deadline_ms.

Retry-richtlijnen

• Probeer 429 / 503 / 504 / 409 opnieuw met exponentiële backoff. Wanneer retry_after_ms aanwezig is, wacht dan minstens zo lang voordat je het opnieuw probeert.
• Probeer 400 / 401 / 402 / 403 nooit opnieuw — het verzoek slaagt pas als je het wijzigt.
• De officiële SDK’s proberen tijdelijke fouten al automatisch opnieuw voor je (standaard 2 retries) en stellen een retryable-vlag beschikbaar op de fout.

Nuttige respons-headers

x-ratelimit-remaining geeft aan hoeveel verzoeken er nog over zijn in de huidige minuut. x-idempotent-replay: true geeft aan dat een respons opnieuw is afgespeeld vanuit de idempotentiecache (je bent niet opnieuw belast).