Skip to main content

2.14 Fehlersuche und Dokumentation von Schnittstellen

APIs und automatisierte Workflows verbinden mehrere technische Systeme miteinander.

Tritt ein Fehler auf, muss geprüft werden:

  • welches System betroffen ist
  • an welcher Stelle der Fehler sichtbar wird
  • wo die eigentliche Ursache liegt
  • welche Daten übertragen wurden
  • welcher Statuscode zurückgegeben wurde
  • ob Authentifizierung und Berechtigungen stimmen
  • welche Änderungen zuletzt durchgeführt wurden
  • ob mehrere Teilsysteme gemeinsam den Fehler erzeugen

Eine Fehlermeldung zeigt häufig nur, wo ein Problem sichtbar wird – nicht zwingend, wo seine Ursache liegt.

Lernziele

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

  • wie Schnittstellenfehler systematisch untersucht werden
  • warum Fehler häufig erst im Zusammenspiel entstehen
  • wie Anforderungen, Datenformate und Abhängigkeiten Fehler verursachen
  • wie Komponenten-, Integrations- und Systemtests unterschieden werden
  • wie Logs und Statuscodes ausgewertet werden
  • was eine Schnittstellendokumentation enthalten sollte
  • wie Störungen nachvollziehbar dokumentiert und übergeben werden

Fehler zuerst eingrenzen

Vor der technischen Analyse sollte geklärt werden:

  • Was funktioniert nicht?
  • Was sollte stattdessen passieren?
  • Seit wann besteht der Fehler?
  • Wer oder was ist betroffen?
  • Tritt der Fehler immer oder nur gelegentlich auf?
  • Funktionieren die einzelnen Teilsysteme?
  • Wurde vorher etwas verändert?
  • Welche Fehlermeldung wird angezeigt?

Genaue Beschreibung:

Der Workflow startet, aber die Gruppenzuweisung schlägt nach der erfolgreichen Benutzeranlage fehl.

Ungenaue Beschreibung:

Die API funktioniert nicht.

Fehlerkategorien

Fehlerbereich Beispiel
Anforderung gewünschtes Verhalten wurde unterschiedlich verstanden
Trigger Webhook startet den Workflow nicht
Software fehlerhafte Logik oder Konfiguration
Elektronik Sensor-, Signal- oder Spannungsproblem
Mechanik Verschleiß, Blockierung oder falsche Ausrichtung
Netzwerk DNS-Fehler, geschlossener Port oder Paketverlust
TLS Zertifikat wird nicht akzeptiert
Authentifizierung Token fehlt oder ist abgelaufen
Autorisierung Rolle oder Scope fehlt
Request Methode, Endpoint oder Body ist falsch
Daten Pflichtfeld oder Datentyp ist falsch
Timing Folgeschritt wird zu früh ausgeführt
Zielsystem API antwortet mit einem Serverfehler
Workflow-Logik Bedingung oder Datenmapping ist falsch
Rate Limit zu viele Anfragen wurden gesendet
Abhängigkeit nachgelagerter Dienst ist ausgefallen

Fehler entstehen häufig im Zusammenspiel

Theoretisch kann die Ursache eines technischen Problems in einem einzelnen Bereich liegen:

  • Software
  • Elektronik
  • Mechanik
  • Netzwerk
  • Konfiguration
  • Bedienung

In der Praxis entstehen viele Fehler jedoch erst durch das Zusammenspiel mehrerer Komponenten.

Einzelne Teilsysteme können für sich betrachtet korrekt funktionieren. Sobald sie miteinander verbunden werden, können dennoch unerwartete Probleme auftreten.

Ein funktionierendes Einzelteil garantiert noch kein funktionierendes Gesamtsystem.

Häufige Ursachen:

  • unterschiedliche Interpretation von Anforderungen
  • fehlerhafte Schnittstellen
  • unterschiedliche Datenformate
  • falsche Einheiten
  • zeitliche Abhängigkeiten
  • falsche Reihenfolge
  • versteckte Systemabhängigkeiten
  • gegenseitige Beeinflussung mehrerer Workflows
  • nicht berücksichtigte Systemzustände

Fehlerstelle und Fehlerursache

Die sichtbare Fehlermeldung muss nicht aus dem Bereich stammen, in dem die eigentliche Ursache liegt.

Beispiel aus einem technischen System:

  1. Ein mechanisches Bauteil bewegt sich schwergängig.
  2. Der Motor benötigt dadurch mehr Strom.
  3. Die Elektronik erkennt eine Überlastung.
  4. Die Steuerungssoftware schaltet das System ab.
  5. Die Software zeigt eine Fehlermeldung an.

Die Meldung erscheint in der Software. Die eigentliche Ursache liegt jedoch in der Mechanik.

Beispiel aus der IT:

  1. Eine Datenbank ist nicht erreichbar.
  2. Die Anwendung kann keine Benutzerdaten laden.
  3. Die API antwortet mit 500 Internal Server Error.
  4. Der n8n-Workflow meldet einen fehlgeschlagenen API-Aufruf.

Der Fehler wird in n8n sichtbar. Die Ursache liegt jedoch bei der Datenbank.

Die Stelle, an der ein Fehler sichtbar wird, ist nicht zwingend die Stelle seiner Ursache.

Unterschiedliche Interpretation von Anforderungen

Anforderungen müssen eindeutig und überprüfbar formuliert sein.

Unklare Anforderung:

Ein Benutzer soll beim Austritt automatisch deaktiviert werden.

Mögliche Interpretationen:

  • sofort nach der Mitteilung
  • am letzten Arbeitstag
  • am Ende des letzten Arbeitstags
  • erst nach der Datenübertragung
  • nur im Hauptsystem
  • gleichzeitig in allen verbundenen Systemen

Alle beteiligten Systeme könnten technisch korrekt funktionieren. Der Gesamtprozess wäre trotzdem falsch, wenn die Anforderung unterschiedlich verstanden wurde.

Mögliche Folgen:

  • Konto wird zu früh gesperrt
  • Konto bleibt zu lange aktiv
  • Daten können nicht mehr übertragen werden
  • einzelne Zugänge bleiben bestehen
  • Lizenzen werden nicht freigegeben

Unklare Anforderungen führen häufig zu technisch korrekten, aber fachlich falschen Lösungen.

Fehler an Schnittstellen

Eine Schnittstelle verbindet zwei Systeme oder Komponenten miteinander.

An einer Schnittstelle müssen beide Seiten dieselben Vereinbarungen verwenden.

Dazu gehören:

  • Datenformat
  • Feldnamen
  • Datentypen
  • Einheiten
  • Protokoll
  • Zeichencodierung
  • Zeitformat
  • Zeitzone
  • Reihenfolge
  • Authentifizierung
  • erwartete Response
  • Fehlerbehandlung

Beispiel: Unterschiedliche Datentypen

Quellsystem:

{
  "active": "true"
}

Zielsystem erwartet:

{
  "active": true
}

Unterschied:

  • "true" ist ein String
  • true ist ein Boolean

Beide Systeme können einzeln korrekt arbeiten. Der Fehler entsteht durch unterschiedliche Erwartungen an der Schnittstelle.

Beispiel: Unterschiedliche Feldnamen

Quellsystem:

{
  "mail": "[email protected]"
}

Zielsystem erwartet:

{
  "primaryEmail": "[email protected]"
}

Ohne korrektes Datenmapping kann das Zielsystem die E-Mail-Adresse nicht zuordnen.

Beispiel: Unterschiedliche Einheiten

Ein Sensor überträgt:

1500 Millivolt

Die Software interpretiert den Wert als:

1500 Volt

Der Messwert wurde korrekt übertragen, aber falsch interpretiert.

Weitere mögliche Verwechslungen:

  • Millimeter und Zentimeter
  • Byte und Bit
  • Kilobyte und Kibibyte
  • Sekunden und Millisekunden
  • Celsius und Fahrenheit
  • UTC und lokale Zeit

Fehler durch Reihenfolge und Timing

Manche Fehler entstehen nur, weil Schritte zu früh, zu spät oder in der falschen Reihenfolge ausgeführt werden.

Beispiel:

  1. Ein Benutzerkonto wird angelegt.
  2. Das Zielsystem benötigt einige Sekunden für die Bereitstellung.
  3. Der Workflow versucht sofort, den Benutzer einer Gruppe hinzuzufügen.
  4. Das Zielsystem kennt den neuen Benutzer noch nicht vollständig.
  5. Die Gruppenzuweisung schlägt fehl.

Die einzelnen Funktionen arbeiten korrekt.

Das Problem entsteht durch das Timing zwischen den Schritten.

Mögliche Lösungen:

  • Verfügbarkeit abfragen
  • Status des Vorgangs prüfen
  • auf ein Folgeereignis warten
  • begrenzten Retry verwenden
  • Backoff einsetzen
  • notwendige Wartezeit einbauen

Ein erfolgreicher API-Request bedeutet nicht immer, dass das Ergebnis sofort in allen Teilsystemen verfügbar ist.

Abhängigkeiten zwischen Systemen

Ein System kann von mehreren weiteren Diensten abhängig sein.

Beispiel:

n8n
  |
  v
API
  |
  v
Benutzerverwaltung
  |
  v
Datenbank

Fällt die Datenbank aus, meldet möglicherweise die API einen Fehler.

n8n zeigt dann einen fehlgeschlagenen API-Aufruf an, obwohl die Ursache in der Datenbank liegt.

Mögliche Abhängigkeiten:

  • DNS
  • Datenbank
  • Authentifizierungsdienst
  • Reverse Proxy
  • Firewall
  • TLS-Zertifikat
  • Cloud-Dienst
  • Speicher
  • Warteschlange
  • externer Anbieter

Verkettete Fehler

Ein einzelner Fehler kann mehrere Folgefehler auslösen.

Beispiel:

  1. DNS-Auflösung schlägt fehl.
  2. API ist nicht erreichbar.
  3. Benutzerkonto wird nicht angelegt.
  4. Gruppenzuweisung kann nicht stattfinden.
  5. Hardware-Aufgabe wird nicht erstellt.
  6. Mehrere Workflow-Schritte melden Fehler.

Die gemeinsame Ursache ist der DNS-Fehler.

Mehrere Fehlermeldungen können dieselbe gemeinsame Ursache besitzen.

Deshalb sollte zuerst der früheste fehlgeschlagene Schritt untersucht werden.

Emergentes Verhalten

Emergentes Verhalten bedeutet:

Das Gesamtsystem zeigt ein Verhalten, das bei der getrennten Betrachtung der Einzelteile nicht erkennbar war.

Beispiele:

  • zwei funktionierende Dienste erzeugen gemeinsam eine Endlosschleife
  • mehrere automatische Retries überlasten das Zielsystem
  • zwei Synchronisierungen überschreiben gegenseitig Änderungen
  • mehrere Zeitpläne starten denselben Prozess gleichzeitig
  • einzeln korrekte Regeln erzeugen gemeinsam falsche Berechtigungen

Emergentes Verhalten entsteht nicht zwingend durch eine defekte Komponente.

Es kann durch die Verbindung, Reihenfolge oder gegenseitige Beeinflussung entstehen.

Beispiel: Gegenseitige Synchronisierung

System A synchronisiert Daten zu System B.

System B synchronisiert dieselben Daten zurück zu System A.

System A ändert Datensatz
          |
          v
System B übernimmt Änderung
          |
          v
System B meldet Änderung zurück
          |
          v
System A verarbeitet sie erneut

Mögliche Folgen:

  • Endlosschleife
  • unnötige API-Anfragen
  • Rate Limit
  • doppelte Benachrichtigungen
  • widersprüchliche Daten

Mögliche Schutzmaßnahmen:

  • führendes Quellsystem festlegen
  • eindeutige Änderungs-ID verwenden
  • Herkunft der Änderung speichern
  • eigene Änderungen nicht erneut verarbeiten
  • Zeitstempel oder Versionen vergleichen

Komponententest

Ein Komponententest prüft eine einzelne Funktion oder Komponente.

Beispiele:

  • API-Endpoint einzeln testen
  • JSON-Validierung prüfen
  • einzelne n8n-Node ausführen
  • Datenbankverbindung testen
  • Sensor einzeln prüfen

Ziel:

Funktioniert die einzelne Komponente für sich?

Integrationstest

Ein Integrationstest prüft das Zusammenspiel mehrerer Komponenten.

Beispiele:

  • n8n überträgt Daten an eine API
  • ein Personalsystem sendet einen Webhook
  • die Benutzerverwaltung weist eine Gruppe zu
  • eine Anwendung speichert Daten in einer Datenbank

Ziel:

Funktionieren die Schnittstellen zwischen den Komponenten?

Systemtest

Ein Systemtest prüft den vollständigen Ablauf unter realistischen Bedingungen.

Beispiel:

Mitarbeiter wird freigegeben
          |
          v
Webhook wird gesendet
          |
          v
Benutzerkonto wird angelegt
          |
          v
Gruppen werden zugewiesen
          |
          v
Hardware-Aufgabe wird erstellt
          |
          v
Ergebnis wird protokolliert

Ziel:

Funktioniert das vollständige Gesamtsystem?

Abnahmetest

Ein Abnahmetest prüft, ob die tatsächlichen fachlichen Anforderungen erfüllt werden.

Beispiele:

  • Konto wird zum richtigen Zeitpunkt aktiviert
  • notwendige Rechte werden vergeben
  • unnötige Rechte werden nicht vergeben
  • Fehler werden korrekt gemeldet
  • Datenschutzanforderungen werden eingehalten
  • zuständige Personen erhalten die benötigten Informationen

Ziel:

Erfüllt die Lösung den vorgesehenen Zweck?

Testebenen im Überblick

Testart Geprüfter Bereich
Komponententest einzelne Funktion oder Komponente
Integrationstest Verbindung zwischen Komponenten
Systemtest vollständiges Gesamtsystem
Abnahmetest fachliche Anforderungen

Ein erfolgreicher Komponententest ersetzt keinen Integrationstest.

Grundregel der Fehlersuche

Empfohlene Reihenfolge:

  1. fachliche Erwartung klären
  2. Fehlerbild genau beschreiben
  3. Trigger prüfen
  4. Eingangsdaten prüfen
  5. Netzwerk und Erreichbarkeit prüfen
  6. Endpoint und HTTP-Methode prüfen
  7. Authentifizierung prüfen
  8. Berechtigungen prüfen
  9. Header und Request-Body prüfen
  10. Statuscode und Response auswerten
  11. Reihenfolge und Timing prüfen
  12. Systemabhängigkeiten untersuchen
  13. letzte Änderungen kontrollieren
  14. Integration und Gesamtsystem testen

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

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?
  • Wurde die Test- oder Produktiv-URL verwendet?

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 die Feldnamen?
  • Enthalten Werte unerwartete Leerzeichen?
  • Entsprechen die Daten der Dokumentation?

Beispiel:

Erwartet:

{
  "active": true
}

Empfangen:

{
  "active": "true"
}

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
  • Netzwerkroute fehlerhaft

Wichtig:

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

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

Endpoint und HTTP-Methode prüfen

Beispiele:

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

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?

Falsch:

Authorization: abc123

Möglicherweise erforderlich:

Authorization: Bearer abc123

Typischer Statuscode:

401 Unauthorized

Autorisierung prüfen

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

Zu prüfen sind:

  • Benutzerrolle
  • 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.

Header und Request-Body prüfen

Typische Header:

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

Typische Fehler:

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

Beispiel:

Gesendet:

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

Erwartet:

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

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 personenbezogene Daten

Fehler reproduzieren

Ein reproduzierbarer Fehler kann gezielt untersucht werden.

Festgehalten werden sollten:

  • genaue Eingabedaten
  • verwendeter Endpoint
  • HTTP-Methode
  • relevante Header
  • Zeitpunkt
  • Statuscode
  • Response
  • betroffene API-Version
  • vorherige Änderungen
  • Reihenfolge der Schritte

Ein Test sollte möglichst erfolgen mit:

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

Einzelne Schritte testen

Ein komplexer Workflow sollte in kleinere Teile zerlegt werden.

Empfohlene Vorgehensweise:

  1. Trigger allein testen
  2. Eingangsdaten prüfen
  3. JSON validieren
  4. Authentifizierung testen
  5. GET-Anfrage ausführen
  6. POST oder PATCH mit Testdaten ausführen
  7. Response auswerten
  8. Folgeschritte einzeln ergänzen
  9. vollständigen Integrationstest durchführen
  10. Gesamtsystem testen

Erst den kleinsten fehlerhaften Schritt finden, danach den vollständigen Ablauf prüfen.

Letzte Änderungen prüfen

Viele Fehler entstehen nach einer Änderung.

Mögliche Änderungen:

  • neues Token
  • neue API-Version
  • geänderter Endpoint
  • neue Benutzerrolle
  • verändertes Datenmapping
  • aktualisierte n8n-Node
  • geänderte Firewall-Regel
  • neuer Proxy
  • neue 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?

Änderungen ganzheitlich prüfen

Eine kleine Änderung kann mehrere Systeme beeinflussen.

Beispiel:

Ein Feld wird von:

department

zu:

departmentName

umbenannt.

Möglicherweise betroffen:

  • Webhook
  • Datenmapping
  • If-Node
  • Switch-Node
  • API-Request
  • Logging
  • Dokumentation
  • weitere Workflows

Vor einer Änderung sollte deshalb geprüft werden:

  • Welche Systeme verwenden das Feld?
  • Welche Workflows sind abhängig?
  • Gibt es Testdaten?
  • Ist ein Rollback möglich?
  • Muss die Dokumentation angepasst werden?

Schnittstellendokumentation

Eine Schnittstellendokumentation beschreibt, wie zwei Systeme miteinander kommunizieren.

Sie sollte enthalten:

  • Zweck der Schnittstelle
  • Quell- und Zielsystem
  • verantwortliche Personen
  • Trigger
  • Endpoints
  • HTTP-Methoden
  • Authentifizierungsverfahren
  • benötigte Scopes
  • Datenformat
  • Feldnamen
  • Datentypen
  • Einheiten
  • Zeitformat und Zeitzone
  • Datenmapping
  • Statuscodes
  • Fehlerbehandlung
  • Retry-Verhalten
  • Rate Limits
  • Logging
  • Datenschutz
  • Testverfahren
  • Wiederherstellungsverfahren

Beispiel einer Kurzdokumentation

Bereich Inhalt
Name Mitarbeiter-Onboarding
Zweck Benutzerkonto automatisiert vorbereiten
Quellsystem Personalsystem
Zielsystem Benutzerverwaltung
Automatisierung n8n
Trigger Webhook
Methode POST
Ressource /users
Datenformat JSON
Zeitformat ISO 8601
Zeitzone Europe/Berlin
Authentifizierung OAuth 2.0
Fehleralarm Kanal #it-support
Verantwortlich interne IT
Testsystem separates Testkonto

Datenmapping dokumentieren

Quellfeld Zielfeld Datentyp Pflicht Beispiel
firstName givenName String ja Max
lastName familyName String ja Mustermann
mail primaryEmail String ja [email protected]
department organization.department String ja IT
active isActive Boolean ja true
startDate custom.startDate Datum nein 2026-08-03

Workflow dokumentieren

Ein Workflow sollte folgende Angaben besitzen:

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

Guter Name:

Mitarbeiter-Onboarding – Benutzerverwaltung

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
  • Benutzerkonto anlegen
  • Gruppenzuweisung prüfen
  • 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 Anpassungen.

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
  • möglicher Datenverlust
  • vorhandener Workaround
  • zeitliche Dringlichkeit

Übergabe an andere Mitarbeiter

Eine Übergabe sollte enthalten:

  • aktueller Stand
  • Fehlerursache, falls bekannt
  • bereits getestete Maßnahmen
  • offene Fragen
  • relevante Logs
  • betroffene Systeme
  • 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, Benutzer-ID 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 Ä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:

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

Praxisbeispiel: Workflow startet nicht

Prüfung:

  1. Workflow aktiv?
  2. Webhook-URL korrekt?
  3. Test- oder Produktiv-URL verwendet?
  4. Quellsystem hat tatsächlich gesendet?
  5. Firewall oder Proxy blockiert?
  6. richtige HTTP-Methode?
  7. Authentifizierung gültig?
  8. Trigger-Log vorhanden?

Mögliche Ursache:

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

Praxisbeispiel: Zusammenspiel mehrerer Workflows

Folgende Regeln gelten:

  • Workflow A deaktiviert Benutzer ohne Abteilung.
  • Workflow B entfernt beim Offboarding die Abteilung.
  • Workflow C reaktiviert Benutzer mit offenen Aufgaben.

Möglicher Ablauf:

  1. Workflow B entfernt die Abteilung.
  2. Workflow A deaktiviert den Benutzer.
  3. Workflow C erkennt offene Aufgaben.
  4. Workflow C aktiviert den Benutzer erneut.

Jeder Workflow arbeitet nach seiner eigenen Regel korrekt.

Das Gesamtergebnis ist dennoch falsch.

Mögliche Lösung:

  • gemeinsame Prozesslogik definieren
  • eindeutigen Mitarbeiterstatus verwenden
  • Prioritäten festlegen
  • gegenseitige Abhängigkeiten dokumentieren
  • vollständigen Systemtest durchführen

Systematische Fehlersuche

Bei einer gestörten Schnittstelle:

  1. fachliche Anforderung klären
  2. Problem genau beschreiben
  3. betroffene Systeme bestimmen
  4. Trigger prüfen
  5. Eingangsdaten prüfen
  6. Erreichbarkeit prüfen
  7. Endpoint und Methode kontrollieren
  8. Authentifizierung prüfen
  9. Autorisierung prüfen
  10. Header und Body prüfen
  11. Statuscode auswerten
  12. Response-Body lesen
  13. Reihenfolge und Timing untersuchen
  14. Abhängigkeiten prüfen
  15. Logs kontrollieren
  16. letzte Änderungen prüfen
  17. Komponenten einzeln testen
  18. Integrationstest durchführen
  19. Gesamtsystem testen
  20. Ursache und Lösung dokumentieren

Wichtige Begriffe

Begriff Bedeutung
Fehlerursache tatsächlicher Auslöser eines Problems
Fehlerstelle Stelle, an der ein Problem sichtbar wird
Fehlereingrenzung Problem Schritt für Schritt lokalisieren
Schnittstellenfehler Fehler bei Übergabe oder Interpretation
Abhängigkeit ein System benötigt ein anderes System
emergentes Verhalten unerwartetes Verhalten des Gesamtsystems
Komponententest einzelne Komponente prüfen
Integrationstest Zusammenspiel mehrerer Komponenten prüfen
Systemtest vollständiges Gesamtsystem prüfen
Abnahmetest fachliche Anforderungen prüfen
Reproduktion Fehler unter gleichen Bedingungen erneut auslösen
Änderungsprotokoll technische Änderungen dokumentieren
Rollback Änderung auf vorherigen Stand zurücksetzen
Workaround vorläufige Umgehung eines Fehlers

Gesamtmerksatz

Technische Fehler liegen nicht immer eindeutig in Software, Elektronik oder Mechanik. Viele Probleme entstehen erst durch unklare Anforderungen, fehlerhafte Schnittstellen, falsche Datentypen, unterschiedliches Timing, versteckte Abhängigkeiten oder das Zusammenspiel mehrerer Teilsysteme. Deshalb müssen neben den einzelnen Komponenten auch ihre Integrationen und das vollständige Gesamtsystem geprüft werden.

Kontrollfragen

Warum zeigt eine Fehlermeldung nicht immer die eigentliche Ursache?

Weil ein Fehler in einem anderen Teilsystem entstehen und erst später sichtbar werden kann.

Warum können funktionierende Komponenten gemeinsam einen Fehler erzeugen?

Weil Schnittstellen, Datenformate, Reihenfolge, Timing oder Abhängigkeiten nicht zusammenpassen.

Was ist ein Schnittstellenfehler?

Ein Fehler bei der Übergabe oder Interpretation von Daten, Signalen oder Befehlen zwischen Systemen.

Was bedeutet emergentes Verhalten?

Das Gesamtsystem zeigt ein Verhalten, das bei der getrennten Betrachtung der Einzelteile nicht erkennbar war.

Was prüft ein Komponententest?

Eine einzelne Funktion oder Komponente.

Was prüft ein Integrationstest?

Das Zusammenspiel und die Schnittstellen zwischen mehreren Komponenten.

Was prüft ein Systemtest?

Den vollständigen Ablauf des Gesamtsystems.

Was prüft ein Abnahmetest?

Ob das System die tatsächlichen fachlichen Anforderungen erfüllt.

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

Der Statuscode zeigt die allgemeine Fehlerklasse. Der Response-Body enthält häufig die genaue Ursache.

Warum ist ein Änderungsprotokoll wichtig?

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

Warum sollte der früheste Fehler eines Ablaufs zuerst untersucht werden?

Weil spätere Fehlermeldungen häufig nur Folgefehler derselben Ursache sind.

Quellen

Back to top