2.14 Fehlersuche und Dokumentation von Schnittstellen

APIs und automatisierte Workflows verbinden mehrere Systeme miteinander.

Tritt ein Fehler auf, muss geprüft werden:

welches System betroffen ist
welcher Schritt fehlgeschlagen ist
welche Daten übertragen wurden
welcher Statuscode zurückgegeben wurde
ob Authentifizierung und Berechtigungen korrekt sind
welche Änderungen zuletzt durchgeführt wurden

Eine strukturierte Fehlersuche grenzt das Problem Schritt für Schritt ein, anstatt mehrere Einstellungen gleichzeitig zu verändern.

Lernziele

Nach dieser Seite solltest du erklären können:

wie API- und Workflow-Fehler systematisch untersucht werden
welche Informationen für die Fehlersuche wichtig sind
wie Logs und Statuscodes ausgewertet werden
wie Fehler reproduziert werden
was eine Schnittstellendokumentation enthalten sollte
warum Änderungen dokumentiert werden müssen
wie Störungen nachvollziehbar übergeben werden

Fehler zuerst eingrenzen

Vor der technischen Analyse sollte geklärt werden:

Was funktioniert nicht?
Seit wann besteht der Fehler?
Wer oder was ist betroffen?
Tritt der Fehler immer oder nur gelegentlich auf?
Wurde vorher etwas verändert?
Funktionieren andere Workflows oder Benutzer?
Welche Fehlermeldung wird angezeigt?

Beispiel:

Der Workflow startet, aber der Benutzer wird nicht im Zielsystem angelegt.

Diese Beschreibung ist genauer als:

Die API funktioniert nicht.

Fehlerkategorien

Fehlerbereich	Beispiel
Trigger	Webhook startet den Workflow nicht
Netzwerk	Zielsystem nicht erreichbar
DNS	Hostname kann nicht aufgelöst werden
TLS	Zertifikat wird nicht akzeptiert
Authentifizierung	Token fehlt oder ist abgelaufen
Autorisierung	Berechtigung oder Scope fehlt
Request	Methode, Endpoint oder Body ist falsch
Daten	Pflichtfeld oder Datentyp ist falsch
Zielsystem	API antwortet mit Serverfehler
Workflow-Logik	Bedingung oder Mapping ist falsch
Rate Limit	zu viele Anfragen
Timeout	Antwort dauert zu lange

Grundregel der Fehlersuche

Empfohlene Reihenfolge:

Trigger prüfen
Eingangsdaten prüfen
Netzwerk und Erreichbarkeit prüfen
Endpoint und HTTP-Methode prüfen
Authentifizierung prüfen
Berechtigungen prüfen
Request-Body und Header prüfen
Statuscode und Response auswerten
Workflow-Logik prüfen
letzte Änderungen kontrollieren

Von außen nach innen prüfen: Auslösung, Verbindung, Zugang, Daten und Verarbeitung.

Schritt 1: Trigger prüfen

Zu prüfen sind:

Ist der Workflow aktiv?
Wurde das Ereignis ausgelöst?
Ist die Webhook-URL korrekt?
Wird die richtige HTTP-Methode verwendet?
Ist der Zeitplan korrekt?
Ist die richtige Zeitzone eingestellt?
Wurde das Ereignis als Duplikat abgelehnt?

Beispiel:

Webhook wurde nicht empfangen
          |
          v
Quellsystem hat gesendet?
     /           \
   nein           ja
   |               |
   v               v
Quelle prüfen   Endpoint prüfen

Schritt 2: Eingangsdaten prüfen

Zu prüfen sind:

Sind alle Pflichtfelder vorhanden?
Sind Felder leer oder null?
Stimmen die Datentypen?
Ist die JSON-Struktur korrekt?
Stimmen Feldnamen und Großschreibung?
Enthalten Werte unerwartete Leerzeichen?
Entsprechen die Daten der Dokumentation?

Beispiel:

Erwartet:

{
  "active": true
}

Empfangen:

{
  "active": "true"
}

Der erste Wert ist ein Boolean, der zweite ein String.

Schritt 3: Erreichbarkeit prüfen

Mögliche Probleme:

DNS-Auflösung fehlerhaft
Port geschlossen
Firewall blockiert
Proxy falsch konfiguriert
Container oder Dienst gestoppt
Zielsystem in Wartung
TLS-Zertifikat ungültig

Wichtig:

Wird keine HTTP-Response empfangen, existiert auch kein HTTP-Statuscode.

Dann liegt möglicherweise ein Netzwerk-, DNS-, TLS- oder Verbindungsfehler vor.

Schritt 4: Endpoint und HTTP-Methode prüfen

Beispiel:

GET /users/15

ruft einen Benutzer ab.

POST /users

legt einen neuen Benutzer an.

Typische Fehler:

falsche API-Version
falscher Ressourcenname
Schreibfehler in der URL
falsche Benutzer-ID
GET statt POST
PUT statt PATCH
nicht unterstützte HTTP-Methode

Beispiel:

DELETE /users

Die API erlaubt möglicherweise nur:

DELETE /users/15

Schritt 5: Authentifizierung prüfen

Zu prüfen sind:

Ist das Credential vorhanden?
Ist das richtige Credential ausgewählt?
Ist das Token gültig?
Ist das Token abgelaufen?
Wurde es widerrufen?
Ist der Authorization-Header korrekt?
Stimmen Client ID und Client Secret?

Beispiel:

Falsch:

Authorization: abc123

Möglicherweise erforderlich:

Authorization: Bearer abc123

Typischer Statuscode:

401 Unauthorized

Schritt 6: Autorisierung prüfen

Die Identität kann gültig sein, obwohl eine Aktion nicht erlaubt ist.

Zu prüfen sind:

Rolle
Gruppenmitgliedschaft
API-Scopes
Administratorfreigabe
Zugriff auf die konkrete Ressource
Least-Privilege-Konfiguration

Typischer Statuscode:

403 Forbidden

Merksatz:

401 bedeutet: Identität nicht bestätigt.
403 bedeutet: Identität bestätigt, aber Zugriff nicht erlaubt.

Schritt 7: Header und Request-Body prüfen

Typische Header:

Authorization: Bearer abc123
Content-Type: application/json
Accept: application/json

Typische Fehler:

Content-Type fehlt
falsches Datenformat
JSON syntaktisch ungültig
Pflichtfeld fehlt
Feldname falsch
falscher Datentyp
Body besitzt falsche Verschachtelung

Beispiel:

{
  "name": "Max Mustermann",
  "department": "IT"
}

Die API erwartet möglicherweise:

{
  "user": {
    "name": "Max Mustermann",
    "department": "IT"
  }
}

Schritt 8: Statuscode auswerten

Code	Typische Prüfung
200	erwartete Daten vorhanden?
201	Ressource tatsächlich erstellt?
400	Request und Pflichtfelder prüfen
401	Token und Authentifizierung prüfen
403	Rolle und Scopes prüfen
404	Endpoint und ID prüfen
409	vorhandene Ressource prüfen
415	`Content-Type` prüfen
422	fachliche Daten prüfen
429	Rate Limit und Wartezeit prüfen
500	Zielsystem und Logs prüfen
502	Proxy oder nachgelagerten Dienst prüfen
503	Verfügbarkeit des Dienstes prüfen
504	Timeout und Antwortzeit prüfen

Der Statuscode sollte immer gemeinsam mit dem Response-Body ausgewertet werden.

Response-Body prüfen

Beispiel:

Status: 400 Bad Request

{
  "error": "Missing required field",
  "field": "email"
}

Der Statuscode zeigt die allgemeine Fehlerklasse.

Der Response-Body nennt häufig:

genaue Ursache
betroffenes Feld
interne Fehlerkennung
Request-ID
empfohlene Maßnahme

Logs verwenden

Logs können zeigen:

Zeitpunkt
Workflow-Ausführung
betroffene Node
Eingangsdaten
Ausgangsdaten
Statuscode
Fehlermeldung
Anzahl der Versuche
Ausführungsdauer

Nicht vollständig protokollieren:

Passwörter
API-Keys
Bearer-Tokens
Refresh Tokens
Client Secrets
vertrauliche Personaldaten

Fehler reproduzieren

Ein reproduzierbarer Fehler kann gezielt untersucht werden.

Dazu sollten festgehalten werden:

genaue Eingabedaten
verwendeter Endpoint
HTTP-Methode
Header
Zeitpunkt
Statuscode
Response
betroffene API-Version
vorherige Änderungen

Ein Test sollte möglichst erfolgen mit:

Testkonto
Testdaten
Test-Endpoint
ungefährlicher Ressource
deaktivierten Löschaktionen

Einzelnen Schritt testen

Ein komplexer Workflow sollte in einzelne Schritte zerlegt werden.

Beispiel:

Webhook allein testen
JSON-Daten prüfen
API-Abfrage mit GET testen
Authentifizierung prüfen
POST mit Testdaten ausführen
Response auswerten
weitere Nodes einzeln hinzufügen

Erst den kleinsten fehlerhaften Schritt finden, danach den Gesamtworkflow prüfen.

Letzte Änderungen prüfen

Viele Fehler entstehen nach einer Änderung.

Mögliche Änderungen:

neues Token
neue API-Version
geänderter Endpoint
neue Rolle
verändertes Datenmapping
aktualisierte Node
geänderte Firewall-Regel
neuer Proxy
geänderte Umgebungsvariable
Softwareupdate

Zu dokumentieren sind:

Was wurde geändert?
Wann wurde es geändert?
Wer hat es geändert?
Warum wurde es geändert?
Wie wurde es getestet?
Wie kann die Änderung zurückgenommen werden?

Schnittstellendokumentation

Eine Schnittstellendokumentation beschreibt, wie zwei Systeme miteinander kommunizieren.

Sie sollte enthalten:

Zweck der Schnittstelle
beteiligte Systeme
verantwortliche Personen
Trigger
Endpoints
HTTP-Methoden
Authentifizierungsverfahren
benötigte Scopes
Datenfelder
Datenmapping
Statuscodes
Fehlerbehandlung
Rate Limits
Zeitpläne
Logging
Datenschutz
Testverfahren
Wiederherstellungsverfahren

Beispiel einer Kurzdokumentation

Bereich	Inhalt
Name	Mitarbeiter-Onboarding
Zweck	Benutzerkonto automatisiert vorbereiten
Quellsystem	Personalsystem
Zielsystem	Google Workspace
Automatisierung	n8n
Trigger	Webhook
Methode	POST
Ressource	`/users`
Datenformat	JSON
Authentifizierung	OAuth 2.0
Berechtigung	Benutzer erstellen
Fehleralarm	Slack-Kanal `#it-support`
Verantwortlich	interne IT
Testsystem	separates Testkonto

Datenmapping dokumentieren

Quellfeld	Zielfeld	Pflicht	Beispiel
`firstName`	`givenName`	ja	Max
`lastName`	`familyName`	ja	Mustermann
`mail`	`primaryEmail`	ja	[email protected]
`department`	`organization.department`	ja	IT
`startDate`	`custom.startDate`	nein	2026-08-03

Dadurch ist nachvollziehbar:

welches Feld woher stammt
wie es im Zielsystem heißt
ob es verpflichtend ist
welches Format erwartet wird

Workflow dokumentieren

Ein Workflow sollte folgende Angaben besitzen:

eindeutiger Name
kurze Beschreibung
verantwortliche Person
verwendete Credentials
Trigger
Eingaben
Verarbeitung
Ausgaben
Fehlerpfad
Abhängigkeiten
letzte Änderung

Guter Name:

Mitarbeiter-Onboarding – Google Workspace

Ungünstiger Name:

Workflow Kopie Neu Final 3

Node-Namen

Nodes sollten nach ihrer Funktion benannt werden.

Gut:

Webhook – Mitarbeiter empfangen
Pflichtfelder prüfen
Benutzer nach E-Mail suchen
Google-Benutzer anlegen
Fehler an IT melden

Ungünstig:

HTTP Request 4
If 2
Node Neu
Test Final

Änderungsprotokoll

Datum	Änderung	Verantwortlich	Ergebnis
18.07.2026	API-Endpoint aktualisiert	interne IT	erfolgreich getestet
19.07.2026	neues Scope ergänzt	Administration	Freigabe dokumentiert
20.07.2026	Fehlerpfad erweitert	interne IT	Test erfolgreich

Ein Änderungsprotokoll erleichtert die Fehlersuche nach Updates.

Störungsdokumentation

Eine gute Störungsmeldung enthält:

kurze Fehlerbeschreibung
betroffene Systeme
Beginn der Störung
Auswirkung
Statuscode oder Fehlermeldung
bereits geprüfte Schritte
vorläufige Ursache
aktuelle Gegenmaßnahme
zuständige Person
nächster Schritt

Beispiel:

Fehler:
Benutzer-Onboarding schlägt bei der Gruppenzuweisung fehl.

Auswirkung:
Benutzerkonto wird erstellt, Gruppe jedoch nicht zugewiesen.

Statuscode:
403 Forbidden

Bereits geprüft:
Token gültig, Endpoint erreichbar, Benutzer vorhanden.

Vermutete Ursache:
benötigter Scope für Gruppenverwaltung fehlt.

Priorisierung von Störungen

Priorität	Beispiel
niedrig	einzelner unkritischer Datensatz
mittel	mehrere Benutzer betroffen
hoch	wichtiger Geschäftsprozess ausgefallen
kritisch	Sicherheitsvorfall oder Datenverlust

Zu berücksichtigen sind:

Anzahl betroffener Benutzer
betriebliche Auswirkung
Sicherheitsrisiko
Datenverlust
vorhandener Workaround
zeitliche Dringlichkeit

Übergabe an andere Mitarbeiter

Eine Übergabe sollte enthalten:

aktueller Stand
Fehlerursache, falls bekannt
getestete Maßnahmen
offene Fragen
betroffene Zugangsdaten oder Rollen
relevante Logs
sichere Wiederholungsmöglichkeit
nächster empfohlener Schritt

Schlechte Übergabe:

Funktioniert nicht. Bitte prüfen.

Bessere Übergabe:

Der POST-Request an /users ist erfolgreich. Die anschließende Gruppenzuweisung antwortet mit 403. Token und Endpoint wurden geprüft. Vermutlich fehlt der Scope für Gruppenänderungen.

Wiederherstellung

Vor größeren Änderungen sollte bekannt sein:

Gibt es ein Backup?
Kann der Workflow exportiert werden?
Kann eine alte Version wiederhergestellt werden?
Können Credentials zurückgesetzt werden?
Können bereits ausgeführte Änderungen rückgängig gemacht werden?
Welche manuellen Schritte sind notwendig?

Mögliche Maßnahmen:

Workflow-Version sichern
Konfiguration exportieren
Testlauf durchführen
Rollback dokumentieren
Änderungen schrittweise veröffentlichen

Praxisbeispiel: Fehlerhafte Benutzeranlage

Fehler:

POST /users

Status: 409 Conflict

{
  "error": "Email already exists"
}

Systematische Prüfung:

Response wurde empfangen.
Endpoint und Methode sind korrekt.
Authentifizierung ist gültig.
E-Mail-Adresse existiert bereits.
vorhandenes Konto wird mit GET gesucht.
Datensatz wird nicht erneut angelegt.
Workflow erstellt eine manuelle Prüfaufgabe.
Ergebnis wird protokolliert.

Praxisbeispiel: Workflow startet nicht

Prüfung:

Workflow aktiv?
Webhook-URL korrekt?
Test- oder Produktiv-URL verwendet?
Quellsystem sendet tatsächlich?
Firewall oder Proxy blockiert?
richtige HTTP-Methode?
Authentifizierung gültig?
Trigger-Log vorhanden?

Mögliche Ursache:

Im Quellsystem wurde noch die Test-Webhook-URL verwendet.

Praxisbeispiel: 403 Forbidden

Prüfung:

Token vorhanden
Token gültig
Benutzer authentifiziert
benötigte Rolle prüfen
API-Scope prüfen
Ressourcenzugriff prüfen
Administratorfreigabe prüfen

Mögliche Lösung:

Fehlenden Scope ergänzen und nur die notwendige Berechtigung freigeben.

Systematische Fehlersuche

Bei einer gestörten Schnittstelle:

Problem genau beschreiben
betroffene Systeme bestimmen
Trigger prüfen
Eingangsdaten prüfen
Erreichbarkeit prüfen
Endpoint und Methode kontrollieren
Authentifizierung prüfen
Autorisierung prüfen
Header und Body prüfen
Statuscode auswerten
Response-Body lesen
Logs kontrollieren
letzte Änderungen prüfen
Fehler mit Testdaten reproduzieren
Lösung testen und dokumentieren

Wichtige Begriffe

Begriff	Bedeutung
Fehlereingrenzung	Problem Schritt für Schritt lokalisieren
Reproduktion	Fehler unter gleichen Bedingungen erneut auslösen
Schnittstellendokumentation	Beschreibung der Kommunikation zwischen Systemen
Datenmapping	Zuordnung von Quell- und Zielfeldern
Änderungsprotokoll	Dokumentation technischer Änderungen
Störungsdokumentation	Beschreibung eines Fehlers und seiner Bearbeitung
Rollback	Änderung auf vorherigen Stand zurücksetzen
Workaround	vorläufige Umgehung eines Fehlers
Priorität	Dringlichkeit und Auswirkung einer Störung
Übergabe	strukturierte Weitergabe an eine andere Person

Gesamtmerksatz

Bei der Fehlersuche werden Trigger, Daten, Verbindung, Endpoint, Authentifizierung, Berechtigungen und Response nacheinander geprüft. Eine vollständige Dokumentation beschreibt Systeme, Datenmapping, Rechte, Fehlerbehandlung und Änderungen, damit Schnittstellen dauerhaft nachvollziehbar betrieben werden können.

Kontrollfragen

Was sollte zuerst geprüft werden, wenn ein Workflow nicht startet?

Trigger, Aktivierungsstatus und Eingang des auslösenden Ereignisses.

Warum müssen Statuscode und Response-Body gemeinsam geprüft werden?

Der Statuscode zeigt die allgemeine Fehlerklasse, während der Response-Body häufig die genaue Ursache nennt.

Was bedeutet Fehler reproduzieren?

Der Fehler wird unter bekannten Bedingungen gezielt erneut ausgelöst.

Was gehört in eine Schnittstellendokumentation?

Beteiligte Systeme, Endpoints, Methoden, Authentifizierung, Datenmapping, Fehlerbehandlung und Verantwortlichkeiten.

Warum ist ein Änderungsprotokoll wichtig?

Damit Fehler mit vorherigen technischen Änderungen in Verbindung gebracht werden können.

Was ist ein Workaround?

Eine vorläufige Lösung, die das Problem umgeht, ohne die eigentliche Ursache vollständig zu beheben.

Warum sollten Nodes verständliche Namen besitzen?

Damit Aufbau, Fehlerstelle und Aufgabe des Workflows schneller erkannt werden.

Was sollte eine gute Störungsübergabe enthalten?

Fehlerbeschreibung, Auswirkung, geprüfte Schritte, Logs, vermutete Ursache und nächsten Schritt.

Warum sollte eine API mit Testdaten geprüft werden?

Damit die Fehlersuche keine unbeabsichtigten Änderungen an Produktivdaten verursacht.

Was ist die wichtigste Grundregel der Fehlersuche?

Nur eine Ursache beziehungsweise Änderung nach der anderen prüfen und die Ergebnisse dokumentieren.

Quellen