Unified Error Handling macht aus jedem Fehler eine vorhersehbare Form

Das Gewicht tragen statusCode und downstreamErrors, und das eine ist genau deshalb normalisiert, damit das andere es nicht sein muss. HTTP ist genau darin, welcher Code zu welcher Lage gehört, und Systeme setzen das so lose um wie alles andere: Ein Validierungsfehler, den keine Wiederholung behebt, kommt von manchen Systemen als 500 zurück. Eine 500 sagt das Gegenteil, nämlich dass auf ihrer Seite etwas kaputtging und dieselbe Anfrage in zehn Minuten durchaus gelingen kann. Maesn antwortet mit dem Code, den die Lage wirklich verlangt, Ihre Retry-Logik liest also eine Kategorie statt eines Irrtums.

Den Code zu korrigieren würde Sie sonst das kosten, was darunter liegt, und das ist oft der einzig nützliche Teil: welches Feld abgewiesen wurde, was das System stattdessen erwartet hat, oder ein eigener Status, der nur dort etwas bedeutet. Das Original wird deshalb nicht ersetzt. Es reist neben dem korrigierten in downstreamErrors, und darum kann Ihre Anwendung auf die Kategorie verzweigen, während ein Entwickler die eigenen Worte des Systems liest, statt dass das eine gegen das andere getauscht wird.

Nicht jedes Problem antwortet mit einem Fehler. Ein Aufruf kann gelingen und trotzdem nicht alles tun, worum Sie gebeten haben, und das kommt als meta.warnings in der Antwort an: ein Feld, das das Zielsystem nicht nutzt, oder ein Wert, den es übergeht, weil es ihn nicht kennt, etwa eine Währung außerhalb der von ihm behandelten. Geschrieben ist das für die anbindenden Entwickler und nicht für den Endnutzer, und es trennt einen Schreibvorgang, der funktioniert hat, von einem, der so funktioniert hat, wie Sie es meinten.

Hier arbeiten zwei Ebenen, und es lohnt sich, sie auseinanderzuhalten, angefangen damit, dass die Tabelle darüber für Ihren Code geschrieben ist und nicht unseren beschreibt. Maesns Ebene ist die Einordnung: Der Fehler kommt mit einer Kategorie an, mit benanntem System und mit angehängter ursprünglicher Antwort, und ungültige Eingaben werden gefangen, bevor sie je ein System erreichen. Die Wiederholung liegt bei Ihnen. Maesn wiederholt und taktet auf den asynchronen Endpunkten, und bei einem synchronen Aufruf gehen die 429, 500 und 503 des Zielsystems direkt durch, damit Ihre Anwendung darauf reagiert. Dieselbe Warteschlange gibt die Anfragen eines Mandanten der Reihe nach frei, und das verhindert, dass sich zwei Token-Refreshes überschneiden und Ihren Kunden eine erneute Authentifizierung kosten.

Wenn Sie doch wissen müssen, was auf der Leitung wirklich geschah, sind die Anfrage, die Antwort und jedes Event darum herum aufgezeichnet, einen sporadischen Fehler zu untersuchen heißt also, ihn über Protokollierung und Monitoring nachzuschlagen statt ihn nachzustellen.