Ihre API gibt `400 Bad Request` mit dem Body `{"error": "invalid input"}` zurück. Ein menschlicher Entwickler öffnet die Dokumentation, überprüft die Payload, entdeckt das fehlende Feld und korrigiert es in einer Minute. Ein Agent liest dieselben zwei Wörter, hat nichts, worauf er reagieren kann, und tut das Einzige, was er kann: sendet dieselbe Anfrage erneut. Dann wieder. Dann gibt er auf und teilt dem Benutzer mit, dass die API defekt ist.
Fehlerantworten sind der Teil einer API, auf den Agenten am meisten angewiesen sind und den Teams zuletzt entwerfen. Ein guter Fehler sagt dem Aufrufer, was schiefgelaufen ist, ob ein erneuter Versuch helfen könnte und was geändert werden muss. Ein Agent kann auf alle drei reagieren. Ein vager Fehler verwandelt ein behebbares Problem in eine fehlgeschlagene Aufgabe.
Dieser Leitfaden ist für die API-Seite der Beziehung geschrieben. Unser Beitrag zur Fehlerbehebung für Agenten behandelt, was der Client mit Wiederholungen, Backoff und Circuit Breakers tun sollte. Dieser hier behandelt, was Ihre API zurückgeben muss, damit diese Client-Logik überhaupt funktioniert.
Apidog ist hier wichtig, weil Fehlerantworten der am wenigsten getestete Teil der meisten APIs sind. Sie können sie in der Spezifikation definieren, mocken und in demselben Bereich, in dem Sie den Erfolgsfall testen, überprüfen.
Die drei Fragen, die ein Fehler beantworten muss
Jede Fehlerantwort, die ein Agent erhält, sollte ihm ermöglichen, drei Dinge ohne Raten zu beantworten.
Ist das mein Fehler oder Ihrer? Ein `4xx` bedeutet, dass die Anfrage falsch war und eine unveränderte Wiederholung erneut fehlschlagen wird. Ein `5xx` bedeutet, dass auf dem Server etwas schiefgelaufen ist und dieselbe Anfrage später erfolgreich sein könnte. Agenten, die diese nicht unterscheiden können, wiederholen entweder bei einem Validierungsfehler ewig oder geben bei einem vorübergehenden Fehler auf.
Soll ich es erneut versuchen und wann? Einige `4xx`-Fehler sind wiederholbar, andere nicht. `429` ist nach einer Wartezeit wiederholbar. `409` kann nach erneutem Lesen des Status wiederholbar sein. `422` ist ohne Änderung der Payload nicht wiederholbar. Sagen Sie explizit, was Sache ist.
Was genau soll ich ändern? Dies ist das Feld, das die meisten APIs weglassen. „Validierung fehlgeschlagen“ ist nutzlos. „Das Feld `customer.postal_code` ist erforderlich, wenn `country` `US` ist“ ist eine Korrektur, die der Agent beim nächsten Versuch anwenden kann.
Fügen Sie diese drei Punkte in jeden Fehler ein, und die meisten Agenten-Wiederholungsstürme verschwinden.
Ein strukturiertes Fehlerformat verwenden
Erfinden Sie keine Form. RFC 9457, Problem Details for HTTP APIs, definiert eine und sie wird gut unterstützt:
{
"type": "https://api.example.com/errors/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "The field 'customer.postal_code' is required when 'country' is 'US'.",
"instance": "/v1/orders",
"errors": [
{
"field": "customer.postal_code",
"code": "required_conditional",
"message": "Required when country is US. Provide a 5-digit or 9-digit US postal code.",
"example": "94107"
}
],
"retryable": false,
"next_action": "Add customer.postal_code to the request body and send again."
}
Vier Teile tragen die Hauptlast für einen Agenten.
`detail` ist ein vollständiger Satz, der das tatsächliche Feld und die tatsächliche Regel benennt. Keine Kategorie. Das spezifische Ding, das bei dieser Anfrage fehlgeschlagen ist.
Das `errors`-Array ist maschinenlesbar, ein Eintrag pro Problem, mit einem Feldpfad, den ein Agent auf die von ihm gesendete Payload zurückführen kann. Geben Sie jeden Fehler sofort zurück. Wenn Sie sie einzeln zurückgeben, wird aus einer einzigen Korrektur fünf Roundtrips.
`retryable` ist ein Boolescher Wert, nichts, was aus einem Statuscode abgeleitet werden sollte. Dies ist die Erweiterung, die Agenten am meisten hilft, und sie kostet ein Feld.
`next_action` ist ein einfacher Anweisungstext. Modelle folgen expliziten Anweisungen in einem Antwort-Body zuverlässiger, als sie aus Fehlercodes ableiten, und ein einziger Satz hier verwandelt oft eine fehlgeschlagene Aufgabe in eine abgeschlossene.
Googles API-Fehlerdesign-Leitfaden kommt von einer anderen Richtung zu ähnlichen Schlussfolgerungen, insbesondere dass Fehlerdetails in eine strukturierte Liste statt in Prosa gehören.
Sagen Sie, wann man zurückkommen soll
Bei allem Vorübergehenden sagen Sie, wann. Ein Agent, der weiß, dass er 30 Sekunden warten muss, wartet 30 Sekunden. Ein Agent, der es nicht weiß, wird etwas wählen, und das Gewählte ist normalerweise zu kurz.
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/problem+json
{
"type": "https://api.example.com/errors/rate-limited",
"title": "Rate limit exceeded",
"status": 429,
"detail": "You have used 1000 of 1000 requests in the current minute window.",
"retryable": true,
"retry_after_seconds": 30,
"next_action": "Wait 30 seconds before sending this request again. Do not retry sooner."
}
Der Retry-After-Header akzeptiert entweder eine Verzögerung in Sekunden oder ein HTTP-Datum; Sekunden sind für einen Client einfacher zu verarbeiten. Senden Sie ihn als Header für Standard-Clients und wiederholen Sie ihn im Body für das Modell. Duplizierung ist günstig, und beide Konsumenten bekommen, was sie am besten lesen. Die Details zur Ratenbegrenzung werden in unserem Leitfaden für überschrittene Ratenbegrenzungen und unter wie man API-Ratenbegrenzung implementiert behandelt, wenn Sie auf der Serverseite stehen.
Dasselbe Muster gilt für `503` während der Wartung und für `409` bei einer gesperrten Ressource. Jeder Fehler, bei dem Warten die richtige Antwort ist, sollte eine Zahl enthalten.
Niemals Interna preisgeben, niemals nichts zurückgeben
Zwei Fehlerarten befinden sich an entgegengesetzten Extremen, und beide schaden Agenten.
Die erste ist der Stack-Trace. Die Rückgabe von internem Ausnahmetext legt Framework-Versionen, Dateipfade und manchmal Abfragefragmente offen. Dies ist ein Sicherheitsproblem, bevor es ein Agentenproblem ist, und die Bedenken in unserem Beitrag zum Testen von APIs gegen nicht vertrauenswürdige Eingaben treffen direkt zu. Es überflutet auch das Kontextfenster mit Text, auf den das Modell nicht reagieren kann.
Die zweite ist der leere Fehler: ein `500` ohne Body oder `{"error": true}`. Der Agent lernt nichts, und seine einzigen Optionen sind Wiederholung oder Abbruch.
Der Mittelweg ist ein stabiler öffentlicher Fehler mit einer Korrelations-ID:
{
"type": "https://api.example.com/errors/internal",
"title": "Internal error",
"status": 500,
"detail": "The order could not be created due to an internal error. No order was created.",
"retryable": true,
"retry_after_seconds": 5,
"request_id": "req_01J8ZK3M2Q",
"next_action": "Retry once after 5 seconds. If it fails again, stop and report request_id req_01J8ZK3M2Q."
}
Der Satz „Es wurde keine Bestellung erstellt“ ist der wertvollste Teil. Agenten, die mit einem mehrdeutigen Schreibvorgang konfrontiert sind, müssen entscheiden, ob ein erneuter Versuch eine Duplikation riskiert, und die meisten entscheiden sich schlecht. Sagen Sie ihnen, in welchem Zustand Sie sich befinden. Wenn Sie das nicht versprechen können, machen Sie die Operation idempotent und sagen Sie dies auch, was das Muster in unserem Beitrag über Idempotenzschlüssel für KI-Agenten ist.
Die `request_id` gibt Ihnen den Faden zurück zu Ihren Logs, wenn ein Mensch schließlich die Transkription liest. Kombinieren Sie sie mit den Praktiken in unserem API-Observability-Leitfaden, damit die ID tatsächlich zu etwas aufgelöst wird.
Fehler gehören in die Spezifikation
Wenn eine Fehlerform nicht in Ihrem OpenAPI-Dokument enthalten ist, existiert sie für generierte Clients, Mocks und Agenten-Tools nicht. Die meisten Spezifikationen beschreiben einen `200` detailliert und winken dann alles andere ab.
responses:
'201':
description: Order created
content:
application/json:
schema: { $ref: '#/components/schemas/Order' }
'422':
description: >
Validation failed. Not retryable without changing the request body.
The errors array names each invalid field.
content:
application/problem+json:
schema: { $ref: '#/components/schemas/Problem' }
'429':
description: >
Rate limited. Retryable. Wait for retry_after_seconds before sending again.
content:
application/problem+json:
schema: { $ref: '#/components/schemas/Problem' }
Diese Beschreibungen sind keine Dekoration. Wenn Sie Agenten-Tools aus der Spezifikation generieren, wie in unserem Leitfaden zum Umwandeln einer OpenAPI-Spezifikation in Agenten-Tools, wird dieser Text zu dem, was das Modell über den Fehlerfall liest. Eine Beschreibung, die „wiederholbar, zuerst warten“ besagt, führt zu einem besseren Verhalten als eine, die „Too Many Requests“ besagt.
Testen Sie die Fehler, nicht nur die Erfolge
Fehlerpfade sind dort, wo die Testabdeckung zusammenbricht, weil das Auslösen Mühe erfordert. Mocking beseitigt den Aufwand.
Definieren Sie jede Fehlerantwort in Ihrem API-Projekt und mocken Sie sie dann, damit der Agent jeden Fall bei Bedarf erfüllen kann. In Apidog können Sie die Fehlerantworten zur Endpunktdefinition hinzufügen und einen Mock zwischen ihnen wechseln, was Ihnen eine wiederholbare Möglichkeit gibt, den Agenten gegen einen `422`, einen `429` und einen `500` laufen zu lassen, ohne etwas Reales zu beschädigen. Unser Beitrag zum Betreiben von Agenten gegen Mocks statt gegen die Produktion behandelt die umfassendere Gewohnheit.
Fünf Fälle zum Erstellen:
- Validierungsfehler mit mehreren fehlerhaften Feldern gleichzeitig. Stellen Sie sicher, dass jedes Problem in einer Antwort zurückkommt und dass der nächste Versuch des Agenten alle Probleme behebt, anstatt nur eines.
- Ratenbegrenzung mit Wartezeit. Stellen Sie sicher, dass der Agent mindestens `retry_after_seconds` wartet, anstatt zu hämmern.
- Serverfehler bei einem Schreibvorgang. Stellen Sie sicher, dass der Agent bei einem erneuten Versuch nicht stillschweigend ein Duplikat erstellt.
- Authentifizierungsfehler. Stellen Sie sicher, dass der Agent stoppt, anstatt es erneut zu versuchen, da keine Wartezeit einen schlechten Token beheben kann. Unser Beitrag zu API-Schlüsseln mit minimalen Rechten für Agenten behandelt die Seite der Anmeldeinformationen.
- Fehlerhafter Fehler-Body. Geben Sie etwas zurück, das kein gültiges JSON ist, und bestätigen Sie, dass der Agent elegant degradiert. Upstream-Proxys werden dies irgendwann mit Ihnen tun.
Speichern Sie die Menge als Szenarien, damit sie in CI ausgeführt werden. Die Fehlerbehandlung verschlechtert sich leise, normalerweise wenn jemand einen Serializer refaktoriert, und die Erfolgsfall-Suite wird es nicht bemerken.
Was bessere Fehler wert sind
Der Wert zeigt sich an drei Stellen, und er ist leicht zu messen, sobald man hinsieht.
Weniger verschwendete Wiederholungen. Ein Agent, der `{"error": "invalid input"}` sieht, versucht die identische Payload typischerweise zwei- oder dreimal erneut, bevor er aufgibt. Jeder Versuch kostet einen Modellzug und die gesamte Konversation als Kontext. Eine Antwort, die das fehlende Feld benennt, führt normalerweise zu einem korrigierten Versuch. Das ist der Unterschied zwischen vier Aufrufen und zwei bei einem routinemäßigen Validierungsfehler.
Weniger Eskalationen. Agenten, die sich nicht erholen können, übergeben die Aufgabe an einen Menschen. Jede vermeidbare Übergabe ist das teure Ergebnis, das der Agent eigentlich verhindern sollte. Fehler, die eine Lösung benennen, halten den Lauf innerhalb der Automatisierung.
Kürzere Fehlersuche. Wenn etwas eine Person benötigt, verwandelt `request_id` plus ein präzises `detail` eine Suche in den Logs in eine einzige Nachschlageoperation. Dies ist dasselbe Argument, das unser API-Observability-Leitfaden über Korrelation anführt, angewendet auf den Moment, in dem ein Lauf abbricht.
Es gibt einen vierten Vorteil, der leicht übersehen wird: dieselben Verbesserungen helfen menschlichen Entwicklern. Niemand hat sich jemals darüber beschwert, dass eine Fehlermeldung zu spezifisch war, welches Feld falsch war.
Auch für die Eskalation konzipieren
Einige Fehler sind für den Agenten tatsächlich nicht behebbar. Ein fehlender Scope, ein geschlossenes Konto, eine Regel, die eine menschliche Entscheidung erfordert. Für diese besteht die Aufgabe des Fehlers darin, sauber zu übergeben: zu sagen, was passiert ist, zu sagen, was eine Person tun muss, und die Korrelations-ID mitzuführen, die die Übergabe kostengünstig macht.
Diese Antwort muss irgendwo landen, wo ein Mensch sie liest. Wenn der Agent eine Code-Laufzeitumgebung ist, die zugewiesene Aufgaben abarbeitet, ist die umgebende Plattform normalerweise der Ort, an dem sie landet. Sharkly speichert das Ergebnis und die Ausführungspur des Agenten bei der Aufgabe und leitet Elemente, die eine Antwort oder Überprüfung benötigen, in einen Posteingang weiter, sodass ein blockierter Lauf als Arbeit sichtbar wird und nicht als Zeile in einem Log. Ihr Fehlertext macht diese Übergabe nützlich, denn eine Meldung mit der Aufschrift „invalid input“ gibt dem Prüfer nicht mehr, als sie dem Agenten gab.
Lassen Sie den Agenten keine Prosa parsen
Ein letztes Anti-Muster, das in organisch gewachsenen APIs häufig vorkommt. Der Statuscode ist korrekt, der Body ist ein Satz, und jeder einzelne Fehler erhält eine andere Formulierung:
{ "message": "Sorry, that didn't work. Please check your details and try again." }
Ein Agent kann darauf nur durch Raten reagieren. Schlimmer noch, Teams kombinieren dies oft mit einem `200`-Status, sodass die Client-Bibliothek nicht einmal einen Fehler sieht.
Zwei Regeln beheben das. Geben Sie jedem einzelnen Fehler einen stabilen, maschinenlesbaren Code, damit der Agent bei `insufficient_funds` statt bei der Phrase „not enough“ verzweigen kann. Und geben Sie niemals einen Fehler mit einem Erfolgsstatuscode zurück, egal wie bequem dies clientseitig argumentiert wird. Ein `200` mit einem Fehler darin ist für jede Wiederholungsstrategie, jedes Dashboard und jede Warnung, die Sie besitzen, unsichtbar.
Eine Checkliste für agentenlesbare Fehler
- Jeder Fehler verwendet ein konsistentes strukturiertes Format über die gesamte API hinweg.
- `detail` benennt das spezifische Feld oder die Bedingung, niemals eine Kategorie.
- Validierungsfehler geben alle Probleme gleichzeitig zurück, mit Feldpfaden.
- Ein `retryable`-Boolescher Wert erscheint bei jedem Fehler.
- Wiederholbare Fehler enthalten eine Wartezeit in Sekunden, sowohl im Header als auch im Body.
- Fehler bei Schreibvorgängen geben an, ob etwas erstellt oder geändert wurde.
- Jeder Fehler enthält eine Korrelations-ID, die in Ihren Logs aufgelöst wird.
- Keine Stack-Traces, keine Framework-Strings, kein SQL.
- Fehlerantworten sind in der Spezifikation mit agentenlesbaren Beschreibungen dokumentiert.
- Mocks existieren für jeden Fehler, und gespeicherte Tests führen sie in CI aus.
Fehler sind eine Schnittstelle. Entwerfen Sie sie für den Aufrufer, den Sie tatsächlich haben, was zunehmend ein Modell ist, das genau das tun wird, was Ihr Antwort-Body ihm sagt. Laden Sie Apidog herunter, um die Fehlerformen zu definieren und sie zu mocken, bevor der Agent sie in der Realität trifft.
Häufig gestellte Fragen
Soll ich RFC 9457 oder mein eigenes Fehlerformat verwenden? Verwenden Sie RFC 9457, es sei denn, Sie haben bereits ein konsistentes Format in Produktion. Konsistenz ist wichtiger als Standardisierung: Die Hälfte Ihrer Endpunkte auf eine neue Form umzustellen, ist schlechter, als eine Form überall beizubehalten. Fügen Sie die `retryable`- und `next_action`-Erweiterungen zu dem von Ihnen verwendeten Format hinzu.
Ist der `next_action`-Text sicher in einer API-Antwort? Ja, wenn Ihr Dienst ihn aus einem festen Satz von Vorlagen generiert. Geben Sie niemals benutzerdefinierte Inhalte in dieses Feld aus, da ein Agent es als Anweisung liest und dies ein Pfad für Prompt-Injection ist. Unser Beitrag zum Testen von APIs gegen nicht vertrauenswürdige Eingaben behandelt das Risiko.
Sollten Validierungsfehler `400` oder `422` sein? Verwenden Sie `400`, wenn die Anfrage fehlerhaft ist, wie z. B. defektes JSON, und `422`, wenn die Anfrage zwar geparst wird, aber Geschäftsregeln verletzt. Agenten profitieren von der Trennung, da die Korrekturen unterschiedlich sind. Wenn Sie bereits eines für beides verwenden, dokumentieren Sie es, anstatt es zu ändern.
Wie viele Details sind zu viele? Hören Sie an dem Punkt auf, an dem der Aufrufer genug Informationen hat, um zu handeln. Feldname, Regel und ein Beispielwert sind normalerweise ausreichend. Interne Identifikatoren, Abfragetext und Stack-Frames überschreiten die Grenze.
Werden Fehlermeldungen im Kontextfenster berücksichtigt? Ja, und ein ausführlicher Fehler, der bei Wiederholungen wiederholt wird, summiert sich schnell. Halten Sie sie unter ein paar hundert Tokens. Unser Beitrag zum Kürzen von API-Antworten für Agenten gilt sowohl für Fehler als auch für Erfolge.
Wie verhindere ich, dass ein Agent einen nicht wiederholbaren Fehler wiederholt? Setzen Sie `retryable: false`, sagen Sie dies in `next_action` und erzwingen Sie es im Tool-Wrapper, damit die Einschätzung des Modells nicht die einzige Schutzmaßnahme ist. Doppelt hält besser ist hier richtig.