Fehlerbehandlung

Auch bei sorgfältig geplanten API-Integrationen können Fehler auftreten. Typische Ursachen sind fehlerhafte Daten, fehlende Berechtigungen, ungültige Statusübergänge, abgelaufene API-Schlüssel, Rate Limits oder temporäre Netzwerkprobleme.

Die tebio API verwendet HTTP-Statuscodes und strukturierte Fehlerantworten, damit externe Systeme Fehler erkennen, klassifizieren und angemessen behandeln können.

Dieser Artikel erklärt die Grundprinzipien der Fehlerbehandlung und zeigt Best Practices für robuste Integrationen.

Grundprinzip

Fehlerbehandlung in API-Integrationen besteht aus drei Ebenen:

1. HTTP-Statuscode: Gibt an, ob ein Request erfolgreich war oder welcher Fehlerbereich betroffen ist.
2. Fehlerantwort: Liefert zusätzliche Informationen zur Ursache des Fehlers.
3. Fachlicher Kontext: Bestimmt, wie Ihr System auf den Fehler reagieren sollte.

Nicht jeder Fehler ist ein technischer Systemfehler.

Ein Validierungsfehler, ein fehlendes Recht oder ein ungültiger Statusübergang sind fachliche oder integrationsbezogene Fehler. Diese sollten anders behandelt werden als ein Timeout oder ein temporärer Serverfehler.

HTTP-Statuscodes verstehen

Die API verwendet HTTP-Statuscodes, um das Ergebnis einer Anfrage einzuordnen.

Erfolgreiche Anfragen

Statuscode	Bedeutung
200 OK	Die Anfrage war erfolgreich.
201 Created	Eine Ressource wurde erfolgreich erstellt.
202 Accepted	Die Anfrage wurde angenommen und wird asynchron weiterverarbeitet.
204 No Content	Die Anfrage war erfolgreich, liefert aber keinen Response Body zurück.

Wichtig: Ein erfolgreicher Statuscode bedeutet nicht immer, dass alle Folgeprozesse bereits abgeschlossen sind.

Beispiel: Ein API-Aufruf kann eine Bestellung erfolgreich annehmen. Rechnungserstellung, Zahlungsabwicklung, Dokumentenerzeugung oder Webhook-Zustellung können anschließend asynchron erfolgen.

Client-Fehler

Client-Fehler deuten in der Regel darauf hin, dass der Request, die Berechtigung oder der fachliche Zustand nicht passt.

Eine unveränderte Wiederholung desselben Requests führt meistens erneut zum Fehler.

Statuscode	Bedeutung
400 Bad Request	Der Request ist syntaktisch fehlerhaft oder enthält ungültige Werte.
401 Unauthorized	Es wurde kein gültiger API-Schlüssel übermittelt.
403 Forbidden	Der API-Schlüssel ist gültig, besitzt aber nicht die erforderliche Berechtigung.
404 Not Found	Die angeforderte Ressource wurde nicht gefunden.
409 Conflict	Der Request steht im Konflikt mit dem aktuellen Zustand der Ressource.
422 Unprocessable Entity	Der Request ist syntaktisch verständlich, verletzt aber fachliche Validierungsregeln.
429 Too Many Requests	Es wurden zu viele Requests in zu kurzer Zeit gesendet.

Server- oder Infrastrukturfehler

Server- oder Infrastrukturfehler weisen auf ein temporäres technisches Problem hin.

Statuscode	Bedeutung
500 Internal Server Error	Ein unerwarteter serverseitiger Fehler ist aufgetreten.
502 Bad Gateway	Ein nachgelagerter Dienst konnte nicht korrekt erreicht werden.
503 Service Unavailable	Der Service ist temporär nicht erreichbar.
504 Gateway Timeout	Ein nachgelagerter Prozess hat nicht rechtzeitig geantwortet.

Bei solchen Fehlern kann eine automatische Wiederholung sinnvoll sein, sofern der Request idempotent verarbeitet werden kann.

Fehlerantworten

Wenn ein API-Aufruf fehlschlägt, kann die API eine strukturierte Fehlerantwort zurückgeben.

Eine typische Fehlerantwort kann Informationen enthalten wie:

• maschinenlesbarer Fehlercode
• lesbare Fehlermeldung
• betroffene Felder
• Validierungsdetails
• technische Referenz oder Trace-ID, sofern verfügbar

Beispielhaftes Fehlerformat:

{
  "errorCode": "validation_error",
  "message": "The provided data is invalid.",
  "errors": [
    {
      "field": "selectionCriteria.entityStatus",
      "issue": "must_not_be_empty"
    }
  ]
}

Typische Bestandteile:

Bestandteil	Bedeutung
errorCode	Maschinenlesbarer Fehlercode zur programmatischen Auswertung
message	Lesbare Beschreibung des Fehlers
errors	Optionale Detailinformationen, zum Beispiel zu ungültigen Feldern
field	Betroffenes Feld oder betroffener Parameter
issue	Art des Validierungs- oder Verarbeitungsproblems

Die genaue Struktur kann je nach Endpunkt und Fehlerart variieren. Die verbindlichen Details finden Sie in der API-Referenz.

Fehlerarten unterscheiden

Für robuste Integrationen ist wichtig, Fehler nicht nur technisch, sondern auch fachlich zu klassifizieren.

Validierungsfehler

Validierungsfehler treten auf, wenn Daten fehlen, ungültig sind oder nicht zur Konfiguration passen.

Beispiele:

• Pflichtfeld fehlt
• ungültiges Datumsformat
• unbekannter Statuswert
• ungültige E-Mail-Adresse
• Produkt passt nicht zum Tenant
• Option gehört nicht zum ausgewählten Produkt
• Zahlungsmethode ist für das Produkt nicht erlaubt

Typische Statuscodes:

• 400 Bad Request
• 422 Unprocessable Entity

Empfohlene Reaktion:

• Request nicht unverändert wiederholen
• Daten korrigieren
• Fehler im externen System sichtbar machen
• bei Benutzerinteraktion konkrete Feldhinweise anzeigen

Berechtigungsfehler

Berechtigungsfehler treten auf, wenn der API-Schlüssel fehlt, ungültig ist oder nicht die erforderlichen Rechte besitzt.

Typische Statuscodes:

• 401 Unauthorized
• 403 Forbidden

Empfohlene Reaktion:

• API-Schlüssel prüfen
• Rollen und Berechtigungen prüfen
• Umgebung prüfen, zum Beispiel Playground oder Live
• keine automatische Wiederholung ohne Konfigurationsänderung

Konfliktfehler

Konfliktfehler treten auf, wenn der Request fachlich nicht zum aktuellen Zustand der Ressource passt.

Beispiele:

• Subscription ist bereits gekündigt
• Bestellung wurde bereits verarbeitet
• Kampagne ist nicht im passenden Status für die gewünschte Aktion
• Ressource ist deaktiviert
• Änderung ist in diesem Status nicht mehr erlaubt

Typischer Statuscode:

• 409 Conflict

Empfohlene Reaktion:

• aktuellen Zustand der Ressource über die API abrufen
• fachlichen Prozess im externen System anpassen
• Statussynchronisation prüfen
• keine blinde Wiederholung desselben Requests

Rate-Limit-Fehler

Rate-Limit-Fehler treten auf, wenn zu viele Requests in kurzer Zeit gesendet werden.

Typischer Statuscode:

• 429 Too Many Requests

Empfohlene Reaktion:

• Verarbeitung pausieren
• Retry-After Header berücksichtigen, sofern vorhanden
• Requests drosseln
• Batch- oder Synchronisationslogik prüfen
• parallele Requests reduzieren

Temporäre technische Fehler

Temporäre technische Fehler können durch Netzwerkprobleme, Timeouts, Wartung oder nachgelagerte Dienste entstehen.

Typische Statuscodes:

• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout

Empfohlene Reaktion:

• Request mit Retry-Strategie wiederholen
• Exponential Backoff verwenden
• maximale Anzahl an Wiederholungen begrenzen
• Fehler protokollieren
• bei wiederholtem Fehler manuelle Prüfung auslösen

Retry-Strategie

Nicht jeder Fehler sollte automatisch erneut versucht werden.

Fehlerart	Automatischer Retry sinnvoll?
400 Bad Request	Nein
401 Unauthorized	Nein
403 Forbidden	Nein
404 Not Found	In der Regel nein
409 Conflict	Nur nach erneuter Zustandsprüfung
422 Unprocessable Entity	Nein
429 Too Many Requests	Ja, nach Wartezeit
5xx	Ja, mit begrenzter Retry-Strategie
Netzwerk-Timeout	Ja, mit begrenzter Retry-Strategie

Empfehlung:

• Wiederholen Sie Requests nur, wenn eine Wiederholung fachlich sicher ist.
• Verwenden Sie Exponential Backoff.
• Begrenzen Sie die Anzahl der Wiederholungen.
• Protokollieren Sie alle fehlgeschlagenen Versuche.
• Planen Sie einen manuellen Klärungsprozess für dauerhaft fehlschlagende Vorgänge ein.

Idempotenz beachten

Bei Retries ist Idempotenz besonders wichtig.

Ein Request ist idempotent, wenn eine mehrfache Ausführung nicht zu mehrfachen unerwünschten Ergebnissen führt.

Beispiel:

Ein mehrfacher Retry darf nicht dazu führen, dass:

• ein Kunde doppelt angelegt wird
• eine Bestellung doppelt ausgelöst wird
• eine Subscription doppelt erstellt wird
• eine Zahlung doppelt gestartet wird
• eine Option mehrfach gebucht wird

Empfehlungen:

• Verwenden Sie externe Referenzen, sofern unterstützt.
• Speichern Sie tebio IDs nach erfolgreicher Erstellung.
• Prüfen Sie vor einem erneuten Create-Request, ob die Ressource bereits existiert.
• Verarbeiten Sie Webhooks idempotent.
• Speichern Sie Event-IDs empfangener Webhooks.

Asynchrone Fehler verstehen

Nicht alle Fehler treten direkt im API-Request auf.

Ein API-Aufruf kann erfolgreich angenommen werden, während ein späterer Folgeprozess fehlschlägt.

Beispiele:

• Bestellung wurde angenommen, aber Zahlung schlägt später fehl
• Subscription wurde erstellt, aber Nachricht konnte nicht versendet werden
• Rechnung wurde erstellt, aber Webhook-Zustellung schlägt fehl
• Option Change wurde gestartet, aber fachliche Prüfung schlägt später fehl
• Kampagnenausführung wurde gestartet, aber einzelne Empfängerprozesse schlagen fehl

Solche Fehler werden häufig über Ereignisse, Statuswerte, Webhooks oder den Ereignisverlauf sichtbar.

Für Integrationen bedeutet das:

• API-Antwort speichern
• Webhooks verarbeiten
• Status später prüfen
• Ereignisverlauf nutzen
• Fehlerfälle nicht nur synchron behandeln

Ereignisverlauf im Portal nutzen

Wenn bei der Entwicklung oder im laufenden Betrieb unklare Fehler auftreten, ist der Ereignisverlauf im tebio Business-Portal hilfreich.

Dort können Business-User und technische Teams nachvollziehen, welche Ereignisse zu einer Ressource protokolliert wurden.

Typische Ressourcen mit Ereignisverlauf:

• Kunde
• Bestellung
• Subscription
• Rechnung
• Zahlung
• Dokument
• Kampagne oder Kampagnenausführung, sofern das Modul verfügbar ist

Der Ereignisverlauf kann Hinweise liefern, warum ein asynchroner Folgeprozess fehlgeschlagen ist.

Beispiele:

• Zahlung wurde vom Anbieter abgelehnt
• Nachricht konnte nicht versendet werden
• Dokumenterzeugung ist fehlgeschlagen
• Statuswechsel wurde nicht erlaubt
• externe Verarbeitung wurde unterbrochen

Fehler im eigenen System protokollieren

Externe Systeme sollten API-Fehler strukturiert protokollieren.

Empfohlene Logdaten:

• Zeitpunkt des Requests
• HTTP-Methode
• Zielressource oder Endpunkt
• Request-ID oder Korrelations-ID, sofern vorhanden
• HTTP-Statuscode
• errorCode
• Fehlermeldung
• betroffene Felder
• tebio Ressourcen-ID, sofern vorhanden
• externe Referenz
• Umgebung, zum Beispiel Playground oder Live

Diese Informationen helfen bei Support, Monitoring und Fehlersuche.

Benutzerfreundliche Fehlermeldungen

Wenn API-Fehler an Endnutzer oder interne Business-User weitergegeben werden, sollten technische Fehlermeldungen übersetzt oder eingeordnet werden.

Beispiel:

Technische Meldung:

selectionCriteria.entityStatus must_not_be_empty

Benutzerfreundliche Meldung:

Bitte wählen Sie mindestens einen Kundenstatus aus.

Empfehlung:

• technische Fehler intern speichern
• verständliche Meldungen im Frontend anzeigen
• keine internen Details oder Secrets an Benutzer ausgeben
• bei unklaren Fehlern eine Support- oder Referenz-ID anzeigen

Monitoring und Alerting

Für produktive Integrationen sollte Fehlerbehandlung überwacht werden.

Empfehlungen:

• Fehlerrate pro Endpunkt überwachen
• 4xx und 5xx getrennt auswerten
• Rate-Limit-Fehler sichtbar machen
• Webhook-Fehler separat überwachen
• wiederholte technische Fehler alarmieren
• fehlgeschlagene fachliche Prozesse in eine Klärungsliste überführen

Ziel ist nicht nur, technische Ausfälle zu erkennen, sondern auch fachliche Integrationsprobleme früh sichtbar zu machen.

Playground für Fehlerszenarien nutzen

Fehlerszenarien sollten vor dem Livegang im Playground getestet werden.

Typische Tests:

• ungültige Pflichtfelder
• fehlende Berechtigungen
• ungültige Produkt- oder Optionskombinationen
• doppelte Requests
• nicht vorhandene Ressourcen
• Rate-Limit-Verhalten
• simulierte Timeouts
• Webhook-Retries
• fehlgeschlagene Zahlungen, sofern im Playground abbildbar

So können Integrationen vor dem produktiven Einsatz robuster gemacht werden.

Typische Fehler vermeiden

Alle Fehler gleich behandeln

Ein Validierungsfehler ist anders zu behandeln als ein temporärer Serverfehler. Klassifizieren Sie Fehler nach Statuscode, Fehlerantwort und fachlichem Kontext.

4xx-Fehler automatisch wiederholen

4xx-Fehler weisen meist auf ein Problem im Request, in der Berechtigung oder im fachlichen Zustand hin. Eine unveränderte Wiederholung löst das Problem in der Regel nicht.

202 Accepted als finalen Erfolg interpretieren

202 Accepted bedeutet, dass die Anfrage angenommen wurde. Die endgültige Verarbeitung kann später erfolgen. Nutzen Sie Webhooks oder Statusabfragen.

Fehlende Idempotenz bei Retries

Retries ohne Idempotenz können doppelte Datensätze oder doppelte Prozesse erzeugen.

Fehler nicht im Portal prüfen

Bei asynchronen Prozessen liefert das Business-Portal häufig zusätzliche Hinweise über Ereignisverlauf, Status und Dokumente.

Keine Trennung zwischen Playground und Live

Fehlerbehandlung sollte in der Playground-Umgebung getestet werden, bevor produktive Prozesse angebunden werden.

API-Hinweis

Die vollständige technische Beschreibung der Statuscodes, Fehlerantworten, möglichen errorCodes und endpoint-spezifischen Fehlermeldungen finden Sie in der separaten API-Referenz.

Dieser Artikel beschreibt die Fehlerbehandlung auf Integrations- und Architekturebene.

Verwandte Themen

• Integration im Überblick
• Typischer API-Workflow
• Webhooks verstehen
• Webhooks einrichten
• Events nachvollziehen
• Portal-Objekte und API-Ressourcen
• API-Referenz
• Playground
• Glossar