Die Antwort zuerst: Jede Energie-API braucht einen fachlichen Fehlervertrag
Stadtwerke sollten eine API nicht allein danach abnehmen, ob sie erreichbar ist, ein gültiges Datenformat liefert und mit einem technischen Erfolgsstatus antwortet. Für den Betrieb zählt, ob der angefragte Fachvorgang eindeutig abgeschlossen, zurückgewiesen, zur späteren Verarbeitung angenommen oder in einen Klärfall überführt wurde. Diese Bedeutungen gehören in einen gemeinsamen Fehlervertrag von Fachbereich, IT, Dienstleister und Betrieb.
Ein solcher Vertrag legt für jeden relevanten Vorgang fest: Was bedeutet Erfolg fachlich? Welche Zustände sind vorläufig? Welche Antwort darf automatisch wiederholt werden? Woran wird ein bereits verarbeiteter Auftrag erkannt? Welche Information braucht der Support? Und ab welchem Punkt muss ein Mensch entscheiden? Erst diese Festlegungen machen aus einer technisch funktionierenden Schnittstelle einen belastbaren Prozess.
Die Bundesnetzagentur führte in ihrer Mitteilung Nr. 55 für den Umsetzungstermin 1. Oktober 2026 neben zahlreichen EDIFACT-Dokumenten auch eine API Guideline sowie API-Webdienste Strom auf. Der verbindliche Detailstand ist den jeweils veröffentlichten Unterlagen zu entnehmen. Das Signal für Energie-IT-Verantwortliche ist dennoch dauerhaft relevant: API-Webdienste stehen nicht neben dem Fachprozess. Sie werden Teil seiner Ausführung und brauchen deshalb dieselbe Sorgfalt bei Status, Prüfung und Klärung wie etablierte Marktkommunikationswege.
Technischer Transport und fachliches Ergebnis sind zwei Ebenen
Eine HTTP-Antwort beschreibt zunächst die Kommunikation zwischen Systemen. Sie kann anzeigen, dass eine Anfrage angenommen, verarbeitet oder technisch nicht verstanden wurde. Der Fachprozess hat jedoch weitere Fragen. Wurde die richtige Markt- oder Messlokation gefunden? Waren Rolle und Gültigkeitszeitraum plausibel? Ist das Ergebnis endgültig oder nur zwischengespeichert? Wurde ein bestehender Vorgang aktualisiert oder versehentlich ein zweiter angelegt?
Diese Ebenen dürfen nicht in einem einzigen Merkmal verschwinden. Eine technisch erfolgreiche Antwort kann einen fachlichen Ablehnungsgrund enthalten. Umgekehrt kann ein technischer Abbruch eintreten, obwohl das Zielsystem den Auftrag bereits verarbeitet hat. Wer in diesem Moment blind wiederholt, riskiert Doppelverarbeitung. Wer nicht wiederholt, riskiert einen fehlenden Vorgang. Genau diese Unsicherheit muss der Fehlervertrag auflösen.
Für jede Operation sollte es deshalb mindestens drei getrennte Aussagen geben: den Transportstatus, den fachlichen Bearbeitungsstatus und den empfohlenen nächsten Schritt. Der nächste Schritt kann Abschluss, erneute Abfrage, sichere Wiederholung, Korrektur der Eingabe oder manuelle Klärung sein. Eine freie Fehlermeldung allein ist dafür zu wenig. Sie hilft beim Lesen, aber selten bei einer verlässlichen automatischen Entscheidung.
Ein kleines Statusmodell verhindert große Missverständnisse
Ein praxistaugliches Statusmodell muss nicht möglichst viele Zustände besitzen. Es muss die Zustände unterscheiden, die zu verschiedenen Handlungen führen. Für viele Vorgänge genügen fünf Klassen: fachlich abgeschlossen, zur Verarbeitung angenommen, fachlich zurückgewiesen, vorübergehend technisch nicht ausführbar und Status unbekannt.
„Zur Verarbeitung angenommen“ ist dabei kein verkleideter Erfolg. Es bedeutet, dass später ein Ergebnis abgefragt oder über einen definierten Rückkanal empfangen werden muss. „Fachlich zurückgewiesen“ verlangt in der Regel eine Korrektur oder Einordnung; eine identische Wiederholung erzeugt nur denselben Fehler. „Vorübergehend nicht ausführbar“ kann eine kontrollierte Wiederholung erlauben. „Status unbekannt“ ist besonders kritisch: Das aufrufende System weiß nicht, ob die Wirkung eingetreten ist, und muss über eine eindeutige Vorgangsreferenz nachfragen können.
Zu jeder Klasse gehören maschinenlesbarer Code, verständlicher Text und eine dokumentierte Handlung. Der Code bleibt stabil, auch wenn der Text verbessert wird. Der Text erklärt den Fall für Betrieb und Support. Die Handlung steuert, ob automatisch gewartet, korrigiert, nachgefragt oder eskaliert wird. So entsteht eine gemeinsame Sprache zwischen Monitoring und Fachteam.
Sichere Wiederholung beginnt mit einer eindeutigen Vorgangsidentität
Zeitüberschreitungen sind im verteilten Betrieb normal. Ein aufrufendes System kann die Verbindung verlieren, nachdem das Zielsystem den Auftrag bereits angenommen hat. Deshalb braucht jeder schreibende oder auslösende Vorgang eine vom Aufrufer kontrollierte, eindeutige Referenz. Kommt derselbe Auftrag mit derselben Referenz erneut, muss das Zielsystem das frühere Ergebnis zurückgeben oder den bestehenden Bearbeitungsstand zeigen, statt eine zweite Wirkung auszulösen.
Diese Eigenschaft wird häufig als Idempotenz bezeichnet. Für den Fachbereich lässt sie sich einfacher formulieren: Derselbe Auftrag mit derselben Identität darf nicht zweimal wirken. Ein geänderter Auftrag benötigt dagegen eine neue Identität oder einen ausdrücklich definierten Änderungsprozess. Andernfalls lässt sich später nicht unterscheiden, ob eine Wiederholung oder eine neue fachliche Absicht vorlag.
Die Vorgangsreferenz sollte von einer Korrelations-ID für den technischen Ablauf begleitet werden. Die fachliche Referenz verbindet alle Versuche desselben Auftrags. Die Korrelations-ID hilft, einen einzelnen Lauf über Gateway, Fachservice, Queue und Antwortweg zu verfolgen. Beide dürfen nicht durch personenbezogene oder vertrauliche Inhalte ersetzt werden. Referenzen sollen auffindbar sein, ohne sensible Nutzdaten in Protokolle zu kopieren.
Monitoring muss die Wirkung beobachten, nicht nur die Verfügbarkeit
Ein grüner Erreichbarkeitstest beweist nur, dass ein Endpunkt antwortet. Für einen Energieprozess sind andere Beobachtungen wichtiger: Wie viele Vorgänge enden fachlich abgeschlossen? Wie lange bleiben angenommene Vorgänge ohne Ergebnis? Welche Ablehnungsgründe treten wiederholt auf? Wie viele Wiederholungen werden benötigt? Wie viele Fälle wechseln in die manuelle Klärung?
Diese Beobachtungen sollten keine pauschale Erfolgskennzahl erzeugen. Ihr Wert liegt in der Diagnose. Viele technische Wiederholungen können auf instabile Abhängigkeiten hinweisen. Wiederkehrende fachliche Ablehnungen können aus Stammdaten, Rollenlogik oder unklarer Validierung entstehen. Eine wachsende Zahl unbekannter Zustände deutet darauf hin, dass Abfrage- oder Rückkanäle fehlen. Erst die Verbindung aus technischem Ereignis und fachlicher Folge zeigt, wo eine Schnittstelle wirklich Arbeit erzeugt.
Auch Protokollierung braucht Grenzen. In Logs gehören Zeitpunkt, Operation, technische und fachliche Referenz, Statuscode, Fehlerklasse, Systemkomponente und Laufzeit. Vollständige Messwerte, Kundendaten, Zugangsdaten oder Nachrichtennutzlasten gehören dort nur hinein, wenn Zweck, Schutz und Aufbewahrung ausdrücklich geklärt sind. Für die Fehlersuche reichen häufig Metadaten und ein kontrollierter Zugriff auf getrennt geschützte Originale.
Der Klärfall ist ein geplanter Prozesszustand
Schnittstellenbetrieb wird unzuverlässig, wenn jeder ungeklärte Fall in einer persönlichen Mail, einem Herstellerticket oder einer Chatnachricht verschwindet. Der Fehlervertrag muss daher auch den Übergang in die manuelle Bearbeitung beschreiben. Ein Klärfall benötigt Vorgangsreferenz, betroffenen Fachprozess, letzten gesicherten Zustand, Fehlerklasse, bereits ausgeführte Wiederholungen, relevante Zeitgrenze und zuständige Rolle.
Wichtig ist die Rückführung. Wird ein Fall fachlich korrigiert, muss das Ergebnis wieder in den maschinellen Prozess gelangen und der ursprüngliche Vorgang eindeutig abgeschlossen werden. Sonst entstehen Schattenstände: Der Support hält den Fall für gelöst, während das Quellsystem weiter auf eine Antwort wartet oder erneut sendet. Eine Klärfallroutine ist deshalb kein Notbehelf außerhalb der Architektur, sondern ein regulärer Zweig des Prozessmodells.
Für Dienstleistervereinbarungen folgt daraus eine konkrete Prüffrage. Es reicht nicht, Reaktionszeiten auf technische Störungen festzulegen. Benötigt werden auch Verantwortlichkeiten für fachliche Fehlerklassen, Zugriff auf nachvollziehbare Referenzen, ein definierter Rückkanal und eine Regel, wer Änderungen am Fehlerkatalog freigibt. So bleiben Fachbedeutung und Betrieb auch über Systemgrenzen hinweg verbunden.
Abnahme mit sechs Testfamilien statt einer Happy-Path-Demo
Eine belastbare Abnahme sollte sechs Testfamilien enthalten. Erstens der Normalfall mit eindeutigem Abschluss. Zweitens eine fachlich unzulässige oder unvollständige Eingabe mit stabilem Fehlercode. Drittens ein vorübergehender technischer Ausfall mit begrenzter, zeitlich gestaffelter Wiederholung. Viertens ein Verbindungsabbruch nach möglicher Verarbeitung, bei dem der Status über die Vorgangsreferenz geklärt wird. Fünftens die identische Wiederholung eines bereits ausgeführten Auftrags ohne zweite Wirkung. Sechstens der Übergang in die manuelle Klärung samt Rückführung.
Jeder Test braucht eine fachliche Erwartung, nicht nur einen erwarteten HTTP-Code. Dokumentiert werden Ausgangsdaten, erlaubte Wirkung, Antwortklasse, nächster Schritt, sichtbare Protokollspur und Ergebnis im führenden System. Bei sensiblen Prozessen sollten synthetische oder ausdrücklich freigegebene Testdaten verwendet werden. So lässt sich Verhalten prüfen, ohne produktive Kunden- oder Prozessdaten in einen Testpfad zu ziehen.
Diese Tests gehören nicht nur vor die erstmalige Einführung. Sie sollten bei Versionswechseln, geänderten Fehlercodes, neuen Dienstleistern und wesentlichen Prozessänderungen erneut laufen. Ein kleiner stabiler Satz aussagekräftiger Grenzfälle schützt den Betrieb besser als eine große Sammlung unklarer Einzelfälle.
Ein umsetzbarer Start in zehn Arbeitstagen
Am ersten Tag wählen Fachbereich und IT genau eine relevante Operation, etwa eine Ermittlung, Statusabfrage oder Übermittlung. Danach erfassen sie alle heute beobachteten Antworten und ordnen jede Antwort einer Statusklasse und einer Handlung zu. In einem dritten Schritt werden fachliche Vorgangsreferenz, technische Korrelations-ID und Protokollfelder festgelegt.
Anschließend werden Wiederholungsregeln und Stop-Kriterien definiert. Kein automatischer Wiederholungsweg darf unbegrenzt laufen. Danach folgt die Klärfallübergabe mit verantwortlicher Rolle und Rückkanal. Zum Abschluss werden die sechs Testfamilien mit synthetischen Daten ausgeführt und die Ergebnisse gemeinsam gelesen. Offene Punkte bleiben als Klärpunkte sichtbar; sie werden nicht durch einen pauschalen Abnahmevermerk verdeckt.
Der wichtigste Prüfpunkt bleibt unabhängig vom Werkzeug: Kann das Stadtwerk für jeden Aufruf erklären, was fachlich geschehen ist, ob eine Wiederholung sicher wäre und wer den nächsten Schritt verantwortet? Wenn diese drei Antworten eindeutig sind, wird aus einer erreichbaren API ein betreibbarer Energieprozess.