Fehlerbehandlung

Die Meirra-API nutzt die üblichen HTTP-Statuscodes, um Erfolg oder Fehlschlag von Anfragen anzuzeigen. Grundsätzlich gilt: • **2xx** – Erfolg. Die Anfrage funktionierte wie erwartet. • **4xx** – Client-Fehler. Die Anfrage war ungültig oder nicht ausführbar. • **5xx** – Serverfehler. Bei uns ist etwas schiefgelaufen. Alle Fehlerantworten verwenden eine konsistente JSON-Struktur mit Fehlercode, Meldung und passenden Details für Diagnose und Handling.

Alle Fehler folgen einem einheitlichen Format: ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Lesbare Fehlerbeschreibung", "details": { ... } } } ``` Das Feld `code` ist ein maschinenlesbarer Fehlercode für Ihre Fehlerlogik. `message` liefert eine für Menschen verständliche Beschreibung. Das optionale `details`-Objekt enthält weiteren Kontext zum jeweiligen Fehler.

Authentifizierungsfehler treten auf, wenn Ihr API-Schlüssel fehlt, ungültig ist oder ihm Berechtigungen fehlen. | Code | HTTP | Beschreibung | |------|------|-------------| | `INVALID_API_KEY` | 401 | API-Schlüssel fehlt oder ist ungültig | | `API_KEY_REVOKED` | 401 | API-Schlüssel wurde widerrufen | | `IP_NOT_ALLOWED` | 403 | Anfrage-IP nicht in der Allowlist | **Beispiel:** ```json { "success": false, "error": { "code": "INVALID_API_KEY", "message": "Der angegebene API-Schlüssel ist ungültig oder fehlt" } } ``` **Behebung:** Prüfen Sie, ob der API-Schlüssel korrekt ist und im Header `x-api-key` mitgesendet wird. Prüfen Sie im Developer-Dashboard, ob der Schlüssel widerrufen wurde.

Guthabenfehler treten auf, wenn Ihr Konto nicht genügend Guthaben für die Anfrage hat. | Code | HTTP | Beschreibung | |------|------|-------------| | `INSUFFICIENT_BALANCE` | 402 | Guthaben für die Anfrage zu niedrig | **Beispiel:** ```json { "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Ihr Guthaben von $0.50 reicht für diese Anfrage nicht aus ($1.00 erforderlich)", "details": { "balanceRemaining": 0.50, "costRequired": 1.00 } } } ``` **Behebung:** Laden Sie Ihr Guthaben im Developer-Dashboard auf. Richten Sie ggf. Warnungen für niedriges Guthaben ein, um Unterbrechungen zu vermeiden.

Rate-Limit-Fehler treten auf, wenn Sie die zulässige Anfragefrequenz überschreiten. | Code | HTTP | Beschreibung | |------|------|-------------| | `RATE_LIMIT_EXCEEDED` | 429 | Zu viele Anfragen | **Beispiel:** ```json { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate Limit überschritten. Erneut in 60 Sekunden versuchen.", "details": { "limit": 1000, "remaining": 0, "resetAt": "2026-02-27T15:30:00Z", "retryAfter": 60 } } } ``` **Behebung:** Implementieren Sie exponentielles Backoff. Beachten Sie den `Retry-After`-Header für den nächsten Versuch. Verteilen Sie Anfragen über die Zeit.

Validierungsfehler treten auf, wenn Anfrageparameter fehlen oder ungültig sind. | Code | HTTP | Beschreibung | |------|------|-------------| | `INVALID_REQUEST` | 400 | Parameter fehlen oder sind ungültig | | `INVALID_EMAIL` | 400 | E-Mail-Format ist ungültig | | `BATCH_TOO_LARGE` | 400 | Batch überschreitet die Maximalgröße | **Beispiel:** ```json { "success": false, "error": { "code": "INVALID_REQUEST", "message": "Validierung der Anfrage fehlgeschlagen", "details": { "field": "email", "issue": "E-Mail ist erforderlich" } } } ``` **Behebung:** Prüfen Sie das Feld `details`, um den genauen Validierungsfehler zu sehen. Stellen Sie sicher, dass alle Pflichtfelder im erwarteten Format vorhanden sind.

Service-Fehler treten auf, wenn in unserer Infrastruktur etwas schiefläuft. | Code | HTTP | Beschreibung | |------|------|-------------| | `SERVICE_ERROR` | 500 | Interner Service-Fehler | | `SERVICE_UNAVAILABLE` | 503 | Dienst vorübergehend nicht verfügbar | | `UPSTREAM_ERROR` | 502 | Externe Abhängigkeit fehlgeschlagen | **Beispiel:** ```json { "success": false, "error": { "code": "SERVICE_ERROR", "message": "Ein interner Fehler ist aufgetreten. Bitte versuchen Sie es später erneut." } } ``` **Behebung:** Das sind transiente Fehler. Implementieren Sie Retry-Logik mit exponentiellem Backoff. Halten die Fehler an, prüfen Sie die Statusseite oder kontaktieren Sie den Support.