Fehlermeldungen, die Nutzenden und Agenten sagen, was als Nächstes zu tun ist

Worum es geht

Eine Fehlermeldung ist die Antwort der Schnittstelle auf zwei Fragen, die Googles Kurs zu Fehlermeldungen (zitiert) in den Mittelpunkt stellt: Was ist schiefgegangen, und wie behebt die nutzende Person es? Die Regeln des Kurses sind: das Problem erklären, die Ursache und die ungültige Eingabe benennen, Anforderungen und Einschränkungen angeben und die Lösung erklären. Microsofts Leitlinien (zitiert) verlangen, dass eine Meldung ein Problem, eine Ursache und eine Lösung nennt und aus Sicht der nutzenden Person geschrieben ist. Für eine Meldung, die von einem Programm oder einem Agenten gelesen wird, muss derselbe Inhalt als Felder verfügbar sein, nicht nur als Fliesstext.

Warum es wichtig ist

Eine vage Meldung («Invalid request») erzeugt ein Support-Ticket, eine Vermutung oder, bei einem automatisierten Client, eine Schleife identischer erneuter Versuche. Die Meldung ist oft die einzige Dokumentation, die die lesende Person in diesem Moment hat. Der Ansatz des Rust-Compilers (zitiert) zeigt, wie weit sich das treiben lässt: Diagnosen tragen strukturierte Vorschläge, die mit einer Anwendbarkeitsstufe gekennzeichnet sind (MachineApplicable, HasPlaceholders, MaybeIncorrect, Unspecified), sodass Werkzeuge automatisch nur die als mechanisch anwendbar markierten übernehmen.

So wird es angewendet

• Die Sache benennen: das Feld, die Datei und Zeile, den tatsächlich erhaltenen Wert, und was stattdessen erwartet wurde («start_date: erwartet wurde ein ISO-8601-Datum wie 2026-09-15, erhalten wurde 15.09.2026»).
• Die Einschränkung nennen, nicht nur den Fehlschlag: die Grenze, die erlaubte Menge, das geforderte Format.
• Sagen, was als Nächstes zu tun ist, und ob eine Wiederholung erfolgreich sein kann: explizit zwischen «Eingabe korrigieren», «warten und erneut versuchen» und «den Betreiber kontaktieren» unterscheiden.
• Jeder unterschiedlichen Ursache eine eigene Meldung und eine stabile, durchsuchbare Kennung geben; die Kennung über Releases hinweg konstant halten, auch wenn sich die Formulierung verbessert.
• Für Agenten und Clients die Bestandteile als Felder bereitstellen: code, field, expected, received, retryable, Dokumentationslink; das Problem-Details-Format für HTTP-APIs (siehe den verwandten Artikel) ist ein Trägerformat dafür.
• Korrekturvorschläge getrennt von der Fehleraussage halten und kennzeichnen, wie sicher sie sind, wie es der Rust-Leitfaden tut; ein automatisch angewendeter falscher Vorschlag ist schlimmer als keiner.
• Interna nie gegenüber Endnutzenden offenlegen (Stack-Traces, Hostnamen, SQL, Geheimnisse); diese mit einer Korrelations-ID protokollieren, die die Meldung anzeigt.
• In einfachen Worten schreiben, ohne Schuldzuweisung, doppelte Verneinung oder Humor; jede Meldung testen, indem man fragt: «Was würde ich jetzt tun?»

Stolpersteine

Sammelmeldungen, die die Ursache verbergen. Meldungen, deren Formulierung sich bei jedem Release ändert und Parser bricht. Vorschläge, die öfter falsch als richtig sind. Validierungsfehler, die einzeln gemeldet werden, obwohl der Client zehn Felder gesendet hat. Preisgabe, ob ein Konto existiert, durch unterschiedliche Meldungen für «falsches Passwort» und «unbekannte Person».