Fehler

Die mail2many API gibt bei Fehlern einen HTTP‑Status‑Code, einen Fehlercode und eine lesbare Meldung zurück. Dies hilft dir, Probleme zu diagnostizieren und zu beheben.

HTTP Status Codes

Code	Bedeutung
200	OK — Anfrage erfolgreich
201	Created — Ressource erstellt
204	No Content — Erfolgreich, ohne Inhalt
400	Bad Request — Ungültige Anfrage
401	Unauthorized — Authentifizierung fehlgeschlagen
404	Not Found — Ressource nicht gefunden
409	Conflict — Ressource existiert bereits
422	Unprocessable Entity — Validierung fehlgeschlagen
429	Too Many Requests — Rate‑Limit überschritten
500	Internal Server Error — Fehler auf dem Server

Fehlercodes

Code	Titel	Beschreibung
401	Ungültige Zugangsdaten	Der API‑Key ist ungültig oder fehlt
1000	Unbekannter Fehler	Ein unerwarteter Fehler ist aufgetreten
1001	Interner Fehler	Ein interner API‑Fehler ist aufgetreten
1002	Validierung fehlgeschlagen	Die übergebenen Daten sind ungültig
1020	Fehler beim Laden der Ressource	Die Ressource konnte nicht gefunden werden
1021	Fehler beim Erstellen der Ressource	Die Ressource konnte nicht erstellt werden
1022	Fehler beim Aktualisieren der Ressource	Die Ressource konnte nicht aktualisiert werden
1023	Fehler beim Löschen der Ressource	Die Ressource konnte nicht gelöscht werden
1024	Ressource existiert bereits	Die Ressource existiert bereits
1025	Ressource ist gesperrt	Die Ressource ist gesperrt und kann nicht bearbeitet werden
1100	Zu viele fehlgeschlagene Authentifizierungen	Der API‑Key wurde zu oft erfolglos verwendet

Fehlerantwort Format

Fehlermeldungen folgen diesem Format:

{
  "status": "error",
  "code": 1002,
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email must be a valid email address."
    ],
    "firstname": [
      "The firstname must be a string."
    ]
  },
  "statusCode": 422
}

Das Feld errors enthält alle ungültigen Felder und die jeweiligen Gründe.

Fehlerbehandlungs-Flow

So gehst du mit verschiedenen Fehlern um:

API Request
    │
    ├─→ 200/201 ✓ Erfolg
    │      └─→ Weiter mit nächstem Request
    │
    ├─→ 400/422 ✗ Validierungsfehler
    │      └─→ errors-Feld prüfen
    │          └─→ Daten korrigieren
    │              └─→ Request wiederholen
    │
    ├─→ 401 ✗ Authentifizierung fehlgeschlagen
    │      └─→ API-Key prüfen
    │          └─→ Korrekten API-Key verwenden
    │              └─→ Request wiederholen
    │
    ├─→ 404 ✗ Ressource nicht gefunden
    │      └─→ ID/Parameter prüfen
    │          └─→ Korrekte Ressource verwenden
    │
    ├─→ 429 ✗ Rate Limit überschritten
    │      └─→ Retry-After Header prüfen
    │          └─→ X Sekunden warten
    │              └─→ Request wiederholen
    │
    └─→ 500 ✗ Server-Fehler
           └─→ Exponential Backoff
               ├─→ Versuch 1: nach 1 Sekunde
               ├─→ Versuch 2: nach 2 Sekunden
               ├─→ Versuch 3: nach 4 Sekunden
               └─→ Maximal 3 Versuche, dann abbrechen

Umgang mit Fehlern

• Überprüfe den statusCode der Response
• Lese die message für eine verständliche Erklärung
• Bei 1002 (Validierung): Prüfe die errors um zu sehen, welche Felder ungültig sind
• Bei 401: Überprüfe deinen API‑Key
• Bei 429: Prüfe Rate Limiting und reduziere Request-Rate oder parallele Anfragen
• Korrigiere die Daten und versuche die Anfrage erneut

Für Fehler spezifisch zu einem Endpoint schau dir die Dokumentation dieses Endpoints an.