Foutafhandeling

De Meirra-API gebruikt de gangbare HTTP-statuscodes om succes of falen van requests aan te geven. In het algemeen: • **2xx** – Succes. De request werkte zoals verwacht. • **4xx** – Clientfout. De request was ongeldig of kan niet worden uitgevoerd. • **5xx** – Serverfout. Er ging iets mis aan onze kant. Alle foutresponsen gebruiken een consistente JSON-structuur met code, bericht en relevante details om het probleem te diagnosticeren en af te handelen.

Alle fouten volgen een consistent formaat: ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Leesbare foutomschrijving", "details": { ... } } } ``` Het veld `code` is een door de machine te lezen code die je in je foutafhandelingslogica kunt gebruiken. Het `message` levert een voor mensen leesbare beschrijving. Het optionele `details`-object bevat extra context die specifiek is voor het type fout.

Authenticatiefouten treden op wanneer je API-sleutel ontbreekt, ongeldig is of geen rechten heeft. | Code | HTTP | Omschrijving | |------|------|--------------| | `INVALID_API_KEY` | 401 | API-sleutel ontbreekt of is ongeldig | | `API_KEY_REVOKED` | 401 | API-sleutel is ingetrokken | | `IP_NOT_ALLOWED` | 403 | IP van de request niet in de allowlist | **Voorbeeld:** ```json { "success": false, "error": { "code": "INVALID_API_KEY", "message": "De opgegeven API-sleutel is ongeldig of ontbreekt" } } ``` **Hoe op te lossen:** Controleer of je API-sleutel klopt en in de header `x-api-key` zit. Kijk in het Developer Dashboard of de sleutel is ingetrokken.

Saldofouten treden op wanneer je account onvoldoende credits heeft voor de request. | Code | HTTP | Omschrijving | |------|------|--------------| | `INSUFFICIENT_BALANCE` | 402 | Saldo te laag voor de request | **Voorbeeld:** ```json { "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Je saldo van $0.50 is onvoldoende voor deze request ($1.00 vereist)", "details": { "balanceRemaining": 0.50, "costRequired": 1.00 } } } ``` **Hoe op te lossen:** Laad je saldo op via het Developer Dashboard. Stel meldingen voor laag saldo in om onderbrekingen te voorkomen.

Rate-limit-fouten treden op wanneer je het toegestane aanroep-tempo overschrijdt. | Code | HTTP | Omschrijving | |------|------|--------------| | `RATE_LIMIT_EXCEEDED` | 429 | Te veel requests | **Voorbeeld:** ```json { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit overschreden. Probeer over 60 seconden opnieuw.", "details": { "limit": 1000, "remaining": 0, "resetAt": "2026-02-27T15:30:00Z", "retryAfter": 60 } } } ``` **Hoe op te lossen:** Pas exponentiële backoff toe. Gebruik de `Retry-After`-header om te weten wanneer je opnieuw mag proberen. Spreid je requests over de tijd.

Validatiefouten treden op wanneer requestparameters ontbreken of ongeldig zijn. | Code | HTTP | Omschrijving | |------|------|--------------| | `INVALID_REQUEST` | 400 | Parameters ontbreken of zijn ongeldig | | `INVALID_EMAIL` | 400 | E-mailformaat is ongeldig | | `BATCH_TOO_LARGE` | 400 | Batch overschrijdt de maximale grootte | **Voorbeeld:** ```json { "success": false, "error": { "code": "INVALID_REQUEST", "message": "Validatie van de request mislukt", "details": { "field": "email", "issue": "E-mail is verplicht" } } } ``` **Hoe op te lossen:** Bekijk het veld `details` voor de specifieke validatiefout. Zorg dat alle verplichte velden in het verwachte formaat zijn meegegeven.

Servicefouten treden op wanneer er iets misgaat in onze infrastructuur. | Code | HTTP | Omschrijving | |------|------|--------------| | `SERVICE_ERROR` | 500 | Interne servicefout | | `SERVICE_UNAVAILABLE` | 503 | Service tijdelijk niet beschikbaar | | `UPSTREAM_ERROR` | 502 | Een externe afhankelijkheid faalde | **Voorbeeld:** ```json { "success": false, "error": { "code": "SERVICE_ERROR", "message": "Er is een interne fout opgetreden. Probeer het later opnieuw." } } ``` **Hoe op te lossen:** Dit zijn tijdelijke fouten. Pas retry-logica toe met exponentiële backoff. Blijven de fouten optreden, raadpleeg dan de statuspagina of neem contact op met support.