Grün, aber leer: Warum n8n-Workflows geänderte API-Antworten nicht bemerken
Am 21. und am 29. September meldete mein Themenscanner jeweils Erfolg. Auf dem Trello-Board kam trotzdem keine einzige neue Karte an. Der Grund war eine geänderte Antwort des Sprachmodells, die mein Code nicht mehr lesen konnte. Am 1. Oktober hat n8n einen Beitrag zu API Contract Testing veröffentlicht, der dieses Muster beschreibt. Zusammen mit meinem Fall zeigt er, wo solche Fehler entstehen und wie du sie abfängst.
Was in meinem Scanner passiert ist
Der Themenscanner ist ein n8n-Workflow, der Themen für diesen Blog sucht. Ein Sprachmodell bewertet jedes Thema, danach legt der Workflow die passenden als Karten in Trello an. Im September habe ich auf ein neueres Modell umgestellt. Das neue Modell schickt vor dem eigentlichen Text einen Block mit seinen Denkschritten. Mein Code las nur den ersten Block der Antwort und fand dort keine Bewertung. Er markierte jedes Thema als Lesefehler. Ein Filter sortierte diese Themen anschließend aus, so wie er es bei fehlerhaften Bewertungen soll. Für n8n war damit jeder einzelne Schritt erfolgreich.
Die Korrektur war klein: Der Code sucht jetzt in der ganzen Antwort nach Textblöcken statt nur an der ersten Stelle. Der nächste Lauf brachte zehn neue Karten.
Was n8n beschreibt
Der n8n-Beitrag nennt ein Beispiel aus dem Zahlungsverkehr. Eine Zahlungs-API liefert einen Betrag als Zahl, nach einem Update kommt derselbe Wert als Text. Die Anfrage gilt trotzdem als erfolgreich. Ein Workflow, der mit einer Zahl rechnet, bildet ab da eine falsche Summe oder verarbeitet gar nichts mehr. Laut n8n kann ein Anbieter so etwas noch Wochen nach bestandenen Tests ändern. Er benennt ein Feld um, ändert einen Datentyp oder macht einen optionalen Wert zur Pflicht.
Eine Grafik im Beitrag zeigt drei weitere Fälle. Im ersten kommen einzelne JSON-Objekte neuerdings als Liste zurück. JSON ist das Textformat, in dem die meisten APIs ihre Daten liefern. Im zweiten ändert sich ein fester Auswahlwert, und der Datensatz landet im falschen Zweig des Workflows. Im dritten liefert die API einen Namen, der bisher in einem Feld stand, verteilt auf zwei Felder. In allen Fällen meldet die Schnittstelle einen gültigen Status. Eine Fehlermeldung, auf die ein Alarm reagieren könnte, gibt es deshalb nicht.
Was ein API-Vertrag festhält
Ein API-Vertrag beschreibt, wie zwei Systeme miteinander sprechen. Er legt den Aufbau von Anfrage und Antwort fest, dazu Pflichtfelder, Datentypen und Statuscodes. Contract Testing prüft, ob sich der Anbieter noch an diese Absprache hält. n8n nennt dafür zwei Wege. Beim verbraucherorientierten Ansatz schreibt die abrufende Seite auf, was sie erwartet, und prüft, ob der Anbieter das weiterhin liefert. Beim schemabasierten Ansatz vergleichst du jede Antwort mit einer festen Beschreibung, etwa einem OpenAPI-Dokument oder einem JSON Schema. Beides hält maschinenlesbar fest, welche Felder und Typen zu erwarten sind.
Warum Tests vor dem Livegang nicht reichen
Contract Testing läuft meist in der CI/CD-Pipeline. So heißt die automatische Prüfstrecke, die neue Versionen vor der Veröffentlichung durchlaufen. Eine Änderung, die der Anbieter Wochen später einführt, bekommt diese Strecke nicht mit. n8n schlägt deshalb vor, die Prüfung in den laufenden Workflow zu bauen. In n8n heißen die einzelnen Bausteine Nodes. Ein HTTP Request Node ruft die API ab. Direkt dahinter vergleicht ein Code Node die Antwort per JavaScript oder Python mit dem erwarteten Schema. Ein If Node trennt zum Schluss gültige Antworten von Abweichungen.
Bei einer Abweichung geht eine Meldung per Slack, E-Mail oder Ticket an die zuständige Person, und der Workflow läuft nicht mit fehlerhaften Daten weiter. Für sensible Abläufe kann vor den nächsten Schritten eine menschliche Freigabe stehen. Jeder Prüflauf landet in der Ausführungshistorie von n8n. Dort siehst du später, was der Anbieter geliefert hat und seit wann die Antwort anders aussieht.
Die Einschränkung im Kleingedruckten
Im Beitrag steht ein Satz, der leicht untergeht: Die Prüfung läuft nicht automatisch und funktioniert nicht mit den eingebauten Nodes. Gemeint sind offenbar die fertigen Bausteine für einzelne Dienste wie Google Sheets oder ein CRM. Den allgemeinen HTTP Request Node empfiehlt n8n ausdrücklich für die Prüfung. Übersehen sollte man den Satz nicht, weil viele Workflows vor allem aus solchen Bausteinen bestehen. Absichern lassen sich solche Strecken trotzdem. Hinter einen eingebauten Node kannst du ebenfalls einen Code Node setzen, der dessen Ausgabe prüft. Damit prüfst du allerdings nur, was der Baustein aus der Antwort gemacht hat. Wer die rohe Antwort prüfen will, ruft die API über den HTTP Request Node ab. Welches Werkzeug zu deinem Team passt, vergleiche ich im Beitrag zu n8n, Make und Zapier.
Der Beitrag stammt von n8n selbst und wirbt am Ende für das eigene Produkt. Laut n8n gelten die Regeln unabhängig vom Werkzeug. Ich sehe das genauso, sofern eine Plattform eigenen Code im Ablauf erlaubt.
Was mein Fall ergänzt
Mein Scanner hatte also eine Prüfung, und sie hat jede leere Bewertung erkannt. Ihr Ergebnis landete aber nur bei dem Filter, der solche Bewertungen aussortiert. Eine Prüfung, die Abweichungen still entfernt, wird so zum nächsten stillen Fehler.
Dazu kommt die Frage, woher eine Änderung stammt. n8n denkt an den Anbieter, der etwas umstellt. Bei mir kam sie durch meinen eigenen Modellwechsel. Wer das Modell oder dessen Einstellungen wechselt, lässt den Workflow danach am besten mit echten Daten laufen und sieht sich das Ergebnis an. Warum solche Fehler im Betrieb so lange unbemerkt bleiben, beschreibe ich im Beitrag zum stillen Fehler in KI-Automationen.
Womit du anfängst
Prüfe die Antwort so nah wie möglich am Abruf, bevor ein anderer Schritt die Daten verarbeitet. Dabei zählt der ganze Vertrag, auch Felder, die dein Workflow heute nicht nutzt. Eine Änderung dort kann laut n8n auf einen Umbau hindeuten, der dich später trifft. Lege außerdem fest, welche Schnittstellen du bei jedem Aufruf prüfst. Für andere reichen geplante Kontrollen, die in festen Abständen nach Abweichungen im Schema suchen.
Die wichtigste Frage klärst du vor dem ersten Alarm: Wer bekommt die Meldung, und wer entscheidet, ob der Workflow pausiert? Bei meinem Scanner hätte schon eine einfache Regel gereicht, die sich meldet, sobald ein Lauf keine einzige Karte anlegt. Wie ich solche Kontrollpunkte grundsätzlich plane, steht unter KI-Automation mit Kontrolle.
