Zum Hauptinhalt springen

Fehlertoleranz

Fehler können in jeder API‑Integration vorkommen. Eine zuverlässige Integration erfordert gutes Error‑Handling und Retry‑Strategien.

Fehler protokollieren​

Wenn ein Endpoint einen Fehler zurückgibt, protokolliere die Anfrage so detailliert wie möglich:

  • Request Body (gesendete Daten)
  • Request Header
  • Response Status Code
  • Response Body (Fehlermeldung)
  • Zeitstempel
  • API‑Key (teilweise, nicht vollständig)

Dies hilft später bei der Diagnose und ermöglicht dir, Anfragen bei Bedarf erneut zu stellen.

Retry‑Strategie​

Manche Fehler sind temporär und lösen sich durch Wiederholung. Nutze folgende Strategie:

Nicht wiederholbar (Fehler, die nicht behoben werden durch erneute Versuche):

  • 401 — Authentifizierung fehlgeschlagen
  • 1002 — Validierung fehlgeschlagen
  • 1024 — Ressource existiert bereits

Wiederholbar (temporäre Fehler):

  • 429 — Rate‑Limit überschritten
  • 500 — Server‑Fehler
  • Netzwerk‑Timeouts

Exponentielles Backoff​

Verwende exponentielles Backoff bei Wiederholungen:

  1. Versuch: sofort
  2. Versuch: 1 Sekunde warten
  3. Versuch: 2 Sekunden warten
  4. Versuch: 4 Sekunden warten
  5. Versuch: 8 Sekunden warten

Brich ab nach max. 5 Versuchen und melde den Fehler.

Rate‑Limiting​

Aktuell gilt: 600 Requests pro Minute pro API-Key. Zusätzlich sind maximal 10 parallele Requests pro API-Key erlaubt.

Wenn du 429 erhältst:

  • Reduziere die Anfragerate
  • Reduziere die Anzahl parallel laufender Requests (z. B. Worker-/Queue-Limit)
  • Implementiere Retry mit Backoff
  • Nutze einen geringeren limit Parameter
  • Verteile Anfragen zeitlich

Details zu Headern (X-RateLimit-Limit, X-RateLimit-Remaining, X-ConcurrencyLimit-Limit, X-ConcurrencyLimit-Remaining) und Fehlerformat findest du unter Rate Limiting.

Idempotenz​

Verwende, wenn möglich, eindeutige IDs zur Idempotenz:

# Mit eindeutiger ID sicher zu wiederholen
curl -X POST "https://YOUR_SERVER-api.mail2many.de/api/v1/subscribers" \
  -H "Idempotency-Key: unique-id-123" \
  --user 'mail2many:YOUR_API_KEY' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Dadurch können Anfragen sicher mehrfach gesendet werden ohne Duplikate zu erstellen.

Monitoring​

Überwache folgende Metriken:

  • Fehlerquote pro Endpoint
  • Durchschnittliche Response‑Zeit
  • 5xx vs. 4xx Fehler
  • Authentifizierungsfehler

Dies hilft dir, Probleme frühzeitig zu erkennen.

Weitere Ressourcen​

Siehe auch die Fehler‑Dokumentation für Details zu spezifischen Fehlercodes.