Konsistente Fehlercodes: eine kleine Taxonomie und sicherere Logs

Warum geworfene Fehler für Nutzer und Teams Chaos verursachen

Wenn jeder Bereich einer App seine eigenen Fehler wirft, sehen Menschen für dasselbe Problem unterschiedliche Meldungen. Ein Anmeldefehler kann auf dem Handy „Something went wrong“ anzeigen, im Web „401“ und in einem Admin-Bildschirm einen roten Stacktrace. Der Nutzer lernt nichts Nützliches, und Ihr Support-Postfach füllt sich mit Screenshots, die nicht zueinander passen.

Diese Inkonsistenz ist der Grund, warum Nutzer Probleme als „es ist kaputt“ oder „es hat nicht funktioniert“ melden. Sie können nicht sagen, ob sie das falsche Passwort eingegeben haben, die Verbindung verloren ging oder ein vorübergehender Ausfall vorliegt. Ohne ein stabiles Signal zum Teilen raten sie, versuchen es erneut oder gehen weg.

Ingenieure spüren es auch. Wenn Fehler einfach geworfen und unverändert angezeigt werden, werden Logs laut: unterschiedlicher Text für dieselbe Grundursache, fehlender Kontext und keine saubere Möglichkeit, Vorfälle zu gruppieren. Ein Bug kann wie 20 verschiedene Probleme aussehen, weshalb es länger dauert, Muster zu erkennen, das Problem zu reproduzieren und einen Fix zu bestätigen.

Rohes Fehlverhalten schafft außerdem ein Sicherheitsrisiko. Ausnahmen enthalten oft Details, die Sie niemals Nutzern zeigen sollten (oder unverschlüsselt in Logs speichern sollten): geheime Schlüssel, Verbindungsstrings, interne Dateipfade, SQL-Snippets oder Nutzerdaten. Ein unbehandelter Fehler kann mehr offenbaren als erwartet.

Ein einfaches System aus konsistenten Fehlercodes behebt das. Nutzer sehen eine klare, sichere Meldung plus einen kurzen Code, den sie teilen können. Ihr Team sieht strukturierte Logs, die an denselben Code gebunden sind, sodass das Debugging schneller geht, ohne sensible Daten preiszugeben.

Was Sie bauen: Codes, Meldungen und nützliche Logs

Sie erstellen einen einfachen Vertrag für Fehlerfälle:

• Ein stabiler Code, der identifiziert, was passiert ist
• Eine nutzersichere Meldung, die erklärt, was als Nächstes zu tun ist
• Logs, die Ihnen helfen, die Grundursache zu beheben

Ein guter Fehlercode ist kein Satz. Er ist ein Bezeichner, der gleich bleibt, auch wenn Sie die Meldung umschreiben, das Framework wechseln oder das gesamte Feature refaktorisieren. Diese Stabilität macht Codes nützlich für Support, Dashboards und Bug-Reports.

Halten Sie die Ebenen getrennt. Nutzer bekommen einfache Sprache und nächste Schritte. Ingenieure bekommen detaillierten Kontext in den Logs. Diese Trennung reduziert auch das Leak-Risiko, weil die Nutzer-Meldung niemals Geheimnisse, Stacktraces, SQL-Fehler oder interne IDs enthalten darf.

Beispiel: Wenn die Anmeldung deshalb fehlschlägt, weil die Datenbank nicht erreichbar ist, sollte der Nutzer sehen: „Wir können Sie gerade nicht anmelden. Versuchen Sie es in ein paar Minuten erneut.“ Der Code könnte AUTH.SERVICE_UNAVAILABLE sein. Die Logs erfassen das Datenbank-Timeout, die fehlschlagende Abhängigkeit und eine Request-ID.

Für ein kleines internes Tool reichen einfache geworfene Fehler vielleicht aus. Sobald Sie echte Nutzer, Support-Tickets oder Compliance-Anforderungen haben, zahlt sich diese Struktur schnell aus.

Beginnen Sie mit einer kleinen Fehlertaxonomie, die Sie wirklich pflegen können

Eine gute Taxonomie ist absichtlich langweilig. Wenn Sie sie nicht ohne Dokument nachschlagen können, ist sie zu groß. Ziel sind konsistente Fehlercodes, die aussagen, welche Art von Problem passiert ist, ohne offenzulegen, wie Ihr Code organisiert ist.

Gruppieren Sie nach Auswirkung für den Nutzer, nicht nach internen Schichten. „DB“ ist nützlich, weil es meist „später nochmal versuchen“ bedeutet. „RepositoryError“ ist nur Ihre Ordnerstruktur, die in die API hineinsickert.

Hier ist ein einfacher Startsatz (6 Gruppen), der die meisten Apps abdeckt:

Zwei Regeln halten das wartbar:

1. Jede Gruppe braucht einen klaren „gehört hierher, wenn...“-Satz, damit Leute nicht stundenlang über Randfälle debattieren.
2. Entscheiden Sie das Retry-Verhalten auf Gruppenebene als Default und überschreiben Sie es nur, wenn nötig.

Wenn ein Nutzer auf „Speichern“ klickt und die App die Datenbank nicht erreichen kann, ist das DB (wiederholbar), selbst wenn der Fehler aus einer Data-Access-Bibliothek stammt. Dagegen ist „E-Mail fehlt @“ immer VALIDATION (nicht wiederholbar), selbst wenn es tief im Code abgefangen wurde.

Fehlercodes so entwerfen, dass sie über die Zeit stabil bleiben

Fehlercodes helfen nur, wenn sie dieselbe Bedeutung nächste Woche noch haben wie heute. Behandeln Sie sie wie eine öffentliche API: Verbessern Sie die Meldung und die Lösung, aber lassen Sie den Code stabil, sobald er ausgeliefert ist.

Wählen Sie ein lesbares Format, das kurz genug ist, um es in Support-Chats zu pasten:

• Verwenden Sie AREA-NNN (Beispiele: AUTH-001, DB-003, PAY-012)
• Lassen Sie das Präfix mit Ihrer Taxonomie übereinstimmen (AUTH, DB, FILE, RATE, PERM)
• Reservieren Sie Nummernbereiche, wenn Sie große Subsysteme haben (AUTH-100+ für OAuth, AUTH-200+ für Sessions)
• Verwenden Sie Nummern nie erneut, selbst wenn ein Problem „gelöst“ ist
• Halten Sie Codes in einer einzigen Quelle der Wahrheit (eine Datei oder Tabelle im Repo)

Entscheiden Sie, was über Releases hinweg stabil bleiben muss: der Code, seine Bedeutung (ein Satz) und die Kategorie. Was sich ändern kann: der nutzerseitige Text, vorgeschlagene nächste Schritte und die internen Details, die Sie loggen.

Trennen Sie außerdem den Code von der Korrelation-ID. Der Nutzer sieht AUTH-001. Ihre Logs erhalten correlation_id=8f3c... plus Stacktrace und Kontext. Support kann nach Code und Korrelation-ID fragen, ohne sensible Interna offenzulegen.

Interne Fehler auf nutzersichere Meldungen abbilden

Nutzer müssen nicht wissen, was innerhalb Ihrer App kaputt gegangen ist. Sie müssen wissen, was passiert ist, was sie als Nächstes tun sollen und wie sie Hilfe bekommen, falls sie stecken bleiben.

Eine nutzersichere Meldung braucht in der Regel drei Teile:

• Was passiert ist (kurz)
• Was als Nächstes zu tun ist
• Was dem Support mitgeteilt werden sollte (der Code)

Beispiel:

„Anmeldung fehlgeschlagen. Bitte versuchen Sie es erneut oder setzen Sie Ihr Passwort zurück. Teilen Sie diesen Code mit dem Support: AUTH-002.“

Halten Sie die Nutzertext von den Entwicklerinformationen getrennt. Die Nutzer-Meldung darf niemals Stacktraces, Tabellennamen, Endpunktpfade, API-Keys, E-Mails oder rohe Tokens enthalten. Diese Details gehören nur in die Logs, und auch dort sollten sie gesäubert sein.

Ein realistisches Beispiel: Ihre Datenbank wirft UniqueViolation, weil eine E-Mail bereits existiert. Intern kann das SQL-Details enthalten. Außen geben Sie zurück: „Diese E-Mail wird bereits verwendet. Versuchen Sie stattdessen, sich anzumelden. Teilen Sie diesen Code mit dem Support: ACC-001.“ Loggen Sie den Ausnahme-Typ und die Request-ID, aber nicht die komplette E-Mail.

Logs nützlich halten, ohne Daten zu leaken

Logs sind für Sie, nicht für Ihre Nutzer. Ziel ist simpel: Wenn etwas fehlschlägt, sollen Sie die genaue Anfrage finden, sehen was kaputt ging und es schnell reparieren können, ohne Passwörter, Tokens oder Kundendaten zu speichern.

Ein guter Default ist, bei jedem Fehler drei Anker zu loggen: den Fehlercode, eine Korrelation-ID und den Ort (Service, Modul, Route oder Handler). Das macht aus einem zufälligen Stacktrace etwas, das Sie suchen und gruppieren können.

Eine einfache Checkliste, die für die meisten Apps funktioniert:

• Immer loggen: error_code, correlation_id, Request-Pfad und wo es passiert ist (Endpoint plus Funktion/Modul).
• Identität sicher loggen: eine interne Nutzer-ID reicht meist; vermeiden Sie E-Mails, Namen oder komplette IP-Adressen, sofern nicht erforderlich.
• Sensible Felder redigieren oder hashen: Passwörter, Tokens, API-Keys, Cookies, Auth-Header und Secrets aus Umgebungsvariablen.
• Log-Level mit Absicht nutzen: WARN für erwartete Fehler (falsche Eingabe, Auth abgelehnt), ERROR für unerwartete Abstürze.
• Aufbewahrung und Zugriff regeln: Logs nur so lange behalten, wie nötig, und einschränken, wer sie einsehen darf.

Ein häufiges Fehlermuster ist „hilfreiches“ Debugging, das komplette Requests oder Environment-Variablen ausdruckt. Das kann Geheimnisse in Logs und Backups leaken. Wenn Sie solchen Code erben, beheben Sie das Logging als erstes. Das reduziert das Risiko sofort, noch bevor Sie jeden Bug gelöst haben.

Schritt für Schritt: Konsistente Fehler in Ihre App einführen

Beginnen Sie damit, eine einzige Fehlerstruktur zu wählen, die jeder Teil der App zurückgeben kann. Das ist es, was konsistente Fehlercodes möglich macht, selbst wenn Fehler aus verschiedenen Bibliotheken kommen.

Eine einfache, praktische Form sieht so aus:

{
  "code": "AUTH_INVALID_CREDENTIALS",
  "message": "Email or password is incorrect.",
  "status": 401,
  "correlationId": "b3f1d2..."
}

Implementieren Sie das in kleinen Schritten:

1. Erstellen Sie einen AppError (oder ähnlich) Typ und einen Helfer zum Erzeugen. Machen Sie code und status verpflichtend und halten Sie message nutzersicher.
2. Fügen Sie einen globalen Handler hinzu, der nicht abgefangene Ausnahmen auffängt (Server-Middleware, API-Gateway-Handler oder App-weite Fehlergrenze). Er sollte immer dieselbe Struktur zurückgeben.
3. Zentralisieren Sie das Exception-Mapping an einer Stelle. Beispiel: Mappen Sie einen Unique-Constraint-Fehler der Datenbank auf CONFLICT_EMAIL_TAKEN, anstatt rohen Text austreten zu lassen.
4. Standardisieren Sie HTTP-Statuscodes, sodass Clients vorhersehbar reagieren können.
5. Fügen Sie Tests hinzu, die sowohl code als auch message prüfen, nicht nur den Status.

Für Statuscodes halten Sie die Menge klein und vorhersehbar:

• 400 für ungültige Eingaben
• 401 für nicht eingeloggt oder falsche Anmeldedaten
• 403 für eingeloggt, aber keine Berechtigung
• 404 für nicht gefundene Ressourcen
• 409 für Konflikte (existiert bereits)

Ein realistisches Szenario: Ein Login-Endpoint wirft „Cannot read properties of undefined“, weil der Request-Body fehlt. Mit einem Mapper wird das zu INPUT_MISSING_FIELDS mit 400 und einer klaren Meldung, während die Logs den Stacktrace an eine correlationId binden.

Häufige Fehlerquellen und wie man sie klassifiziert

Die meisten Apps versagen an denselben wenigen Stellen. Wenn Sie diese Stellen benennen und jedes Mal gleich behandeln, bekommen Sie klarere Support-Tickets und weniger „es ist kaputt“-Meldungen.

Eine nützliche Regel: Klassifizieren Sie nach dem, was der Nutzer als Nächstes tun kann, nicht nach dem exakten Exception-Text. Zwei Stacktraces können unterschiedlich aussehen, aber dennoch bedeuten „nochmal anmelden“ oder „später versuchen“.

Auth und Berechtigungen sollten „muss sich neu anmelden“ von „Zugriff verweigert“ trennen, damit die UI weiß, ob sie zum Login auffordern oder eine Berechtigungs-Meldung zeigen soll. Input und Validierung sollten codes zurückgeben, die der Nutzer beheben kann und, wenn möglich, auf das Feld hinweisen, ohne Serverdetails preiszugeben.

Datenbank- und Storage-Fehler sollten „nicht gefunden“ von „Abfrage fehlgeschlagen“ trennen, weil sie zu unterschiedlichen Maßnahmen führen (leeren Zustand zeigen vs. später erneut versuchen). Externe Dienste sollten danach klassifiziert werden, ob ein Retry jetzt, später oder nie sinnvoll ist. Dateien und Uploads sollten spezifisch genug sein, damit der Nutzer eine andere Datei wählen kann, dürfen aber niemals Dateiinhalte in Logs spiegeln.

Häufige Fehler, die das Fehlerhandling verschlechtern

Die meisten Fehler in der Fehlerbehandlung entstehen, weil Teams für „es zum Laufen bringen“ optimieren statt für „wartbar halten“. Einige Gewohnheiten verwandeln kleine Bugs in Stunden des Rätselns und können sensible Daten leaken.

Fehler, die Support und Vertrauen schaden

Die menschliche Fehlermeldung als „Code“ zu verwenden, ist eine häufige Falle. Meldungen ändern sich beim Umschreiben von Text, beim Übersetzen oder beim Hinzufügen von Details. Support kann dann nicht zuverlässig suchen und Clients können kein stabiles Verhalten aufbauen.

Eine andere Falle ist, mit einem riesigen Katalog zu starten. Wenn Sie am ersten Tag 200+ Codes erstellen, pflegt sie niemand und Leute erfinden neue Codes nach Gutdünken. Eine kleine, klare Menge, die Sie wiederverwenden, schlägt eine lange Liste, die Sie ignorieren.

Roher Exception-Text darf niemals Nutzer oder API-Clients erreichen. Er enthält oft Stacktraces, Tabellennamen, Dateipfade oder Hinweise, die einem Angreifer helfen könnten.

Das vollständige Loggen von Request-Bodies ist ein weiteres vermeidbares Risiko. Es ist ein einfacher Weg, Passwörter, Tokens, API-Keys oder persönliche Daten zu erfassen. Logs sollten beim Debuggen helfen, ohne selbst zur Datenpanne zu werden.

Und mischen Sie verschiedene Fehlerarten nicht. „Nicht gefunden“ wie ein „Serverfehler“ zu behandeln, versteckt echte Zuverlässigkeitsprobleme und macht Alerting laut und ungenau.

Schnelle Checkliste vor dem Release

Vor dem Release machen Sie eine Runde, die Nutzererfahrung, den API-Vertrag und das, was Ihr Team um 2 Uhr morgens sehen wird, überprüft:

• Nutzeransicht: Jeder Fehler zeigt eine einfache Meldung plus einen nächsten Schritt (erneut versuchen, neu anmelden, Support kontaktieren). Keine rohen Stacktraces.
• API-Ansicht: Jede Fehlerantwort enthält einen stabilen Fehlercode und eine Korrelation-ID, die auch in Server-Logs erscheint.
• Logging-Sicherheit: Logs enthalten niemals Secrets (API-Keys), Tokens, Passwörter, Einmalcodes oder vollständige Zahlungsdaten. Wenn Sie eine Kennung loggen müssen, maskieren Sie sie.
• Retry-Verhalten: Wiederholbare Fehler sind klar markiert und werden sanft gehandhabt (kurzer Backoff, begrenzte Wiederholungen und eine klare „nochmal versuchen“-Meldung).
• Support-Workflow: Jemand kann das Problem mit nur dem Fehlercode und der Korrelation-ID diagnostizieren, ohne den Nutzer zu bitten, Dev-Tools-Ausgaben zu kopieren.

Ein einfacher Test: Lösen Sie drei häufige Fehler aus (falsches Passwort, abgelaufene Session, Server-Timeout). Wenn der Nutzer weiß, was als Nächstes zu tun ist und Ihr Team die exakte Log-Zeile mit der Korrelation-ID findet, sind Sie bereit.

Ein realistisches Beispiel: Einen chaotischen Login-Absturz in einen klaren Code verwandeln

Ein häufiges Prototyp-Problem: Ein Login-Flow funktioniert am Montag, dann landet am Dienstag ein Quick-Update und plötzlich sind alle ausgesperrt. Einige Nutzer sehen „Something went wrong“, andere eine leere Seite, und Ihr Team sieht einen Stacktrace, der eine Datenbank-Fehlermeldung und eine Auth-Library im selben Atemzug nennt.

Mit konsistenten Fehlercodes entscheiden Sie, was dieser Ausfall für Nutzer und Support bedeutet. Hier scheitert die App beim Erstellen einer Session nach der Validierung der Anmeldedaten. Sie klassifizieren es als Authentifizierungsproblem und mappen es auf AUTH-003 (z. B. „Session creation failed“).

Was der Nutzer bei AUTH-003 sieht:

• „Wir konnten Sie nicht anmelden. Bitte versuchen Sie es in einer Minute erneut."
• „Wenn das Problem weiterhin besteht, kontaktieren Sie den Support und teilen Sie diesen Code mit: AUTH-003 und ID: 7F2K9."

Diese Meldung ist ehrlich, kurz und sicher. Sie erwähnt keine Tabellen, Tokens, Provider oder andere Interna.

Unterdessen behalten Ihre Logs die Details, aber nur das, was Sie sicher speichern können: den Code, die Korrelation-ID, die Request-Route, die Build-Version und die interne Grundursache (z. B. „DB timeout while writing session row“). Sensible Felder sollten redigiert werden (E-Mail gehasht, IP abgeschnitten, keine Passwörter, keine kompletten Tokens).

Support kann nun schnell triagieren. Ein Nutzer schickt „AUTH-003, 7F2K9“ und Ihr Team kann eine exakte Log-Trail aufziehen, statt zu raten.

Nächste Schritte zur Bereinigung eines bestehenden Codebestands

Beginnen Sie mit Beweisen. Ziehen Sie die letzten 1–2 Wochen Logs und die häufigsten Support-Tickets, und listen Sie die Top-20 Fehlernachrichten, die Nutzer tatsächlich sehen. Meistens finden Sie Wiederholungen: Timeouts, Auth-Fehler, fehlende Datensätze und generische „Something went wrong“-Abstürze.

Fügen Sie Struktur schrittweise hinzu. Wählen Sie einen stark frequentierten Endpoint oder einen Screen (Login, Checkout, Datei-Upload) und führen Sie dort zuerst konsistente Fehlercodes ein. Wenn das stabil ist, erweitern Sie zum nächsten Bereich.

Ein Rollout-Plan, der in echten Teams funktioniert:

• Gruppieren Sie die Top-Fehler in 5–8 Kategorien (auth, validation, dependency, permissions, not found, internal).
• Fügen Sie eine einzelne Mapping-Schicht hinzu, die geworfene Ausnahmen in {code, userMessage, logContext} übersetzt.
• Pflegen Sie eine kleine Docsammlung für Codes: was sie bedeuten, wer sie besitzt und wann ein neuer Code erlaubt ist.
• Fügen Sie Tests für das Mapping hinzu (zunächst reicht ein Test pro Code).
• Prüfen Sie die Logs, um sicherzustellen, dass Sie nützlichen Kontext behalten und gleichzeitig Geheimnisse und persönliche Daten entfernen.

Wenn Sie einen AI-generierten Codebestand geerbt haben, erwarten Sie unvorhersehbare Throws, gemischte Fehlerstrukturen und versteckte Sicherheitsprobleme (wie Geheimnisse in Logs oder rohe DB-Fehler in Responses). In diesem Fall bringt das Stabilisieren der Fehlergrenze und das Bereinigen des Loggings oft den schnellsten Gewinn.

Wenn Sie eine zweite Meinung zu einem AI-generierten Projekt möchten, das Fehler leakt oder unordentliche Logs produziert, konzentriert sich FixMyMess (fixmymess.ai) auf die Diagnose und Reparatur von Problemen wie kaputter Auth, riskantem Logging und Spaghetti-Architektur. Ihr kostenloses Code-Audit kann Ihnen helfen, die größten Fehlerquellen zu identifizieren, bevor Sie Änderungen einleiten.