API-Fehlerdesign für KI-Agenten: Behebbare Fehler

Agentenlesbare API-Fehler: Antworten entwerfen, die wirklich weiterhelfen

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: Er sendet dieselbe Anfrage erneut. Dann wieder. Dann gibt er auf und teilt dem Benutzer mit, dass die API defekt ist.

Apidog heute ausprobieren

Fehlerantworten sind der Teil einer API, auf den Agenten am meisten angewiesen sind und den Teams zuletzt entwerfen. Ein guter Fehler sagt dem Aufrufer:

1. Was ist schiefgelaufen?
2. Ist ein erneuter Versuch sinnvoll – und wenn ja, wann?
3. Was muss geändert werden?

Ein Agent kann auf alle drei Fragen reagieren. Ein vager Fehler verwandelt dagegen ein behebbares Problem in eine fehlgeschlagene Aufgabe.

Dieser Leitfaden richtet sich an die API-Seite der Beziehung. Der Leitfaden zur Fehlerbehebung für Agenten behandelt, was der Client mit Wiederholungen, Backoff und Circuit Breakers tun sollte. Hier geht es darum, was Ihre API zurückgeben muss, damit diese Client-Logik funktioniert.

Apidog ist dafür besonders nützlich: Fehlerantworten sind der am wenigsten getestete Teil der meisten APIs. In Apidog können Sie sie in der Spezifikation definieren, mocken und im selben Bereich testen wie den Erfolgsfall.

Die drei Fragen, die jeder Fehler beantworten muss

Jede Fehlerantwort, die ein Agent erhält, sollte ohne Raten folgende Fragen beantworten.

Ist das mein Fehler oder Ihrer?

Ein 4xx bedeutet, dass die Anfrage fehlerhaft war. Eine unveränderte Wiederholung wird erneut fehlschlagen.

Ein 5xx bedeutet, dass auf dem Server etwas schiefgelaufen ist. Dieselbe Anfrage könnte später erfolgreich sein.

Agenten, die diese Fälle nicht unterscheiden können, wiederholen bei einem Validierungsfehler endlos oder geben bei einem vorübergehenden Serverfehler zu früh auf.

Soll ich es erneut versuchen – und wann?

Nicht jeder 4xx-Fehler ist gleich:

• 429 ist nach einer Wartezeit wiederholbar.
• 409 kann nach einem erneuten Lesen des aktuellen Status wiederholbar sein.
• 422 ist ohne Änderung der Payload nicht wiederholbar.

Sagen Sie explizit, welcher Fall vorliegt.

Was genau soll ich ändern?

Diesen Teil lassen die meisten APIs weg. „Validierung fehlgeschlagen“ ist nutzlos. Dagegen ist folgende Meldung direkt umsetzbar:

Das Feld customer.postal_code ist erforderlich, wenn country den Wert US hat.

Fügen Sie diese drei Informationen in jeden Fehler ein, und die meisten Wiederholungsstürme von Agenten verschwinden.

Ein strukturiertes Fehlerformat verwenden

Erfinden Sie kein eigenes Format. RFC 9457, Problem Details for HTTP APIs, definiert ein etabliertes Format:

{
  "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 Felder tragen dabei die Hauptlast:

• detail ist ein vollständiger Satz, der das konkrete Feld und die konkrete Regel benennt. Verwenden Sie keine allgemeine Kategorie.
• errors ist maschinenlesbar und enthält einen Eintrag pro Problem. Jeder Eintrag sollte einen Feldpfad enthalten, den der Agent auf die gesendete Payload zurückführen kann. Geben Sie alle Fehler auf einmal zurück – sonst wird aus einer Korrektur schnell eine Serie von fünf Roundtrips.
• retryable ist ein boolescher Wert. Der Client sollte diesen Wert nicht selbst aus dem Statuscode ableiten müssen.
• next_action ist eine klare Handlungsanweisung. Modelle folgen expliziten Anweisungen im Response-Body zuverlässiger, als sie Verhalten aus Fehlercodes ableiten.

Auch Googles API-Fehlerdesign-Leitfaden kommt zu einer ähnlichen Schlussfolgerung: Fehlerdetails gehören in eine strukturierte Liste und nicht nur in Prosa.

Sagen Sie, wann der Client wiederkommen soll

Bei vorübergehenden Fehlern muss die Antwort eine konkrete Wartezeit enthalten. Ein Agent, der weiß, dass er 30 Sekunden warten muss, wartet 30 Sekunden. Ohne diese Information wählt er selbst eine Dauer – normalerweise eine zu kurze.

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 Clients einfacher zu verarbeiten.

Senden Sie die Wartezeit als Header für Standard-Clients und wiederholen Sie sie im Body für das Modell. Die Duplizierung ist günstig, und beide Konsumenten erhalten die Information in der Form, die sie am zuverlässigsten lesen.

Weitere Details finden Sie im Leitfaden für überschrittene Ratenbegrenzungen und im Beitrag darüber, wie man API-Ratenbegrenzung implementiert.

Dasselbe Muster gilt für 503 während einer Wartung und für 409 bei einer gesperrten Ressource. Jeder Fehler, bei dem Warten die richtige Reaktion ist, sollte eine konkrete Zahl enthalten.

Niemals Interna preisgeben – und niemals nichts zurückgeben

Zwei Fehlerarten liegen an entgegengesetzten Enden des Spektrums. Beide schaden Agenten.

Stack-Traces

Die Rückgabe interner Ausnahmetexte kann Framework-Versionen, Dateipfade und sogar Abfragefragmente offenlegen. Das ist zuerst ein Sicherheitsproblem. Die Hinweise zum Testen von APIs gegen nicht vertrauenswürdige Eingaben sind hier direkt relevant.

Stack-Traces überfluten außerdem das Kontextfenster mit Informationen, auf die ein Agent nicht sinnvoll reagieren kann.

Leere Fehler

Ein 500 ohne Body oder eine Antwort wie {"error": true} hilft ebenfalls nicht. Der Agent lernt nichts und hat nur zwei Optionen: Wiederholen oder abbrechen.

Der bessere 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 dabei besonders wertvoll. Bei einem mehrdeutigen Schreibvorgang muss ein Agent entscheiden, ob ein erneuter Versuch eine Duplikation erzeugen könnte. Sagen Sie deshalb, in welchem Zustand sich die Operation befindet.

Wenn Sie das nicht garantieren können, machen Sie die Operation idempotent und dokumentieren Sie es. Das Muster für Idempotenzschlüssel bei KI-Agenten beschreibt diesen Ansatz ausführlicher.

Die request_id führt Menschen zurück zu den zugehörigen Logs. Kombinieren Sie sie mit den Praktiken aus dem API-Observability-Leitfaden, damit sich die ID tatsächlich in einen konkreten Vorgang auflösen lässt.

Fehler gehören in die Spezifikation

Wenn ein Fehlerformat nicht in Ihrem OpenAPI-Dokument enthalten ist, existiert es für generierte Clients, Mocks und Agenten-Tools praktisch nicht. Viele Spezifik 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, wie im Leitfaden zum [Umwandeln einer OpenAPI-Spezifikation in Agenten-Tools](https://apidog.com/de/blog/openapi-spec-as-agent-tools?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation), Agenten-Tools aus der Spezifikation generieren, liest das Modell diese Texte beim Umgang mit Fehlerfällen.

„Wiederholbar, aber erst nach einer Wartezeit“ führt zu besserem Verhalten als „Too Many Requests“.

![Ein Entwickler arbeitet an einem Laptop vor einer leuchtenden API-Dashboard-Oberfläche mit Datenflusslinien, die die Komplexität der API-Kommunikation und der Fehlerbehandlung symbolisieren.](https://assets.apidog.com/blog-next/2026/08/image-116.png?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation)

## Testen Sie Fehler, nicht nur Erfolge

Fehlerpfade haben oft eine schlechtere Testabdeckung, weil ihr Auslösen zusätzlichen Aufwand erfordert. Mocking beseitigt diesen Aufwand.

Definieren Sie jede Fehlerantwort in Ihrem API-Projekt und mocken Sie sie anschließend. In Apidog können Sie Fehlerantworten zur Endpunktdefinition hinzufügen und zwischen ihnen wechseln. So testen Sie einen Agenten wiederholbar gegen `422`, `429` und `500`, ohne reale Daten zu beschädigen.

Der Beitrag zum [Betreiben von Agenten gegen Mocks statt gegen die Produktion](https://apidog.com/de/blog/ai-agents-mock-apis-not-production?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) beschreibt diese Praxis ausführlicher.

Erstellen Sie mindestens diese fünf Szenarien:

1. **Validierungsfehler mit mehreren fehlerhaften Feldern:** Prüfen Sie, dass jedes Problem in einer Antwort zurückkommt und der nächste Versuch alle Probleme behebt.
2. **Ratenbegrenzung mit Wartezeit:** Prüfen Sie, dass der Agent mindestens `retry_after_seconds` wartet, statt weiter Anfragen zu senden.
3. **Serverfehler bei einem Schreibvorgang:** Prüfen Sie, dass ein erneuter Versuch nicht stillschweigend ein Duplikat erstellt.
4. **Authentifizierungsfehler:** Prüfen Sie, dass der Agent stoppt. Kein Warten kann einen ungültigen Token reparieren. Die Seite der Berechtigungen behandelt der Beitrag zu [API-Schlüsseln mit minimalen Rechten für Agenten](https://apidog.com/de/blog/ai-agent-api-key-least-privilege?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).
5. **Fehlerhafter Fehler-Body:** Geben Sie absichtlich ungültiges JSON zurück und prüfen Sie, ob der Agent kontrolliert degradiert. Upstream-Proxys werden dies früher oder später mit Ihrer API tun.

Speichern Sie diese Fälle als Szenarien und führen Sie sie in CI aus. Fehlerbehandlung verschlechtert sich häufig stillschweigend, etwa nach einer Änderung am Serializer. Eine Testsuite, die nur den Erfolgsfall prüft, erkennt das nicht.

## Was bessere Fehler wert sind

Der Nutzen zeigt sich an drei Stellen und lässt sich messen.

### Weniger verschwendete Wiederholungen

Ein Agent, der `{"error": "invalid input"}` erhält, versucht die identische Payload typischerweise zwei- oder dreimal erneut. 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. Bei einem routinemäßigen Validierungsfehler kann das den Unterschied zwischen vier und zwei Aufrufen ausmachen.

### Weniger Eskalationen

Agenten, die sich nicht selbstständig erholen können, übergeben die Aufgabe an einen Menschen. Jede vermeidbare Übergabe ist ein teures Ergebnis, das der Agent eigentlich verhindern sollte. Fehler, die eine konkrete Lösung nennen, halten den Lauf in der Automatisierung.

### Kürzere Fehlersuche

Wenn ein Mensch eingreifen muss, verwandeln `request_id` und ein präzises `detail` die Suche in den Logs in eine einzige Nachschlageoperation.

Es gibt außerdem einen oft übersehenen Vorteil: Dieselben Verbesserungen helfen menschlichen Entwicklern. Niemand hat sich je darüber beschwert, dass eine Fehlermeldung zu genau angibt, welches Feld falsch ist.

## Auch für die Eskalation konzipieren

Einige Fehler sind für einen Agenten tatsächlich nicht behebbar:

- ein fehlender Scope,
- ein geschlossenes Konto,
- eine Regel, die eine menschliche Entscheidung erfordert.

Bei diesen Fehlern besteht die Aufgabe der Antwort darin, sauber zu übergeben:

1. Was ist passiert?
2. Was muss ein Mensch tun?
3. Welche Korrelations-ID gehört zu diesem Vorgang?

Die Antwort muss dort landen, wo Menschen sie lesen. Wenn ein Agent in einer Code-Laufzeitumgebung zugewiesene Aufgaben bearbeitet, ist die umgebende Plattform dafür meist der richtige Ort.

Sharkly speichert beispielsweise das Ergebnis und die Ausführungsspur des Agenten an der Aufgabe und leitet Elemente, die eine Antwort oder Überprüfung benötigen, in einen Posteingang weiter. So wird ein blockierter Lauf als Arbeit sichtbar und nicht nur als Zeile in einem Log.

Ihr Fehlertext macht diese Übergabe nützlich. Eine Meldung wie „invalid input“ hilft dem Prüfer nicht mehr als dem Agenten.

## Lassen Sie Agenten keine Prosa parsen

Ein weiteres Anti-Pattern findet sich häufig in organisch gewachsenen APIs: Der Statuscode ist korrekt, aber jeder Fehler erhält eine andere Formulierung.

json
{
"message": "Sorry, that didn't work. Please check your details and try again."
}

Ein Agent kann darauf nur raten. Noch problematischer wird es, wenn solche Fehler mit einem `200`-Statuscode zurückgegeben werden. Dann erkennt die Client-Bibliothek den Fehler möglicherweise überhaupt nicht.

Zwei Regeln beheben das:

1. Geben Sie jedem Fehler einen stabilen, maschinenlesbaren Code. Ein Agent kann auf `insufficient_funds` zuverlässig verzweigen, statt nach der Phrase „not enough“ zu suchen.
2. Verwenden Sie niemals einen Erfolgsstatuscode für einen Fehler. Ein `200` mit Fehlerdaten ist für Wiederholungsstrategien, Dashboards und Warnungen unsichtbar.

## Checkliste für agentenlesbare Fehler

- Jeder Fehler verwendet über die gesamte API hinweg ein konsistentes strukturiertes Format.
- `detail` benennt das konkrete Feld oder die konkrete Bedingung, niemals nur eine Kategorie.
- Validierungsfehler geben alle Probleme gleichzeitig und mit Feldpfaden zurück.
- Jeder Fehler enthält ein `retryable`-Feld.
- 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 werden kann.
- Keine Stack-Traces, Framework-Strings oder SQL-Abfragen werden veröffentlicht.
- Fehlerantworten sind mit agentenlesbaren Beschreibungen in der Spezifikation dokumentiert.
- Für jeden Fehler existieren Mocks und gespeicherte Tests, die in CI ausgeführt werden.

Fehler sind eine Schnittstelle. Entwerfen Sie sie für den Aufrufer, den Sie tatsächlich haben – zunehmend ein Modell, das genau das tut, was Ihr Response-Body vorgibt.

Mit [Apidog](https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) können Sie Fehlerformate definieren und mocken, bevor ein Agent in der Realität auf sie trifft.

## Häufig gestellte Fragen

### Soll ich RFC 9457 oder ein 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 ein neues Format umzustellen, ist schlechter, als ein Format überall beizubehalten.

Erweitern Sie das vorhandene Format um `retryable` und `next_action`.

### Ist `next_action` in einer API-Antwort sicher?

Ja, wenn Ihr Dienst den Wert aus einem festen Satz von Vorlagen generiert. Geben Sie niemals benutzerdefinierte Inhalte in dieses Feld aus. Ein Agent liest es als Anweisung, wodurch ein Pfad für Prompt-Injection entstehen kann.

Mehr dazu finden Sie im Beitrag zum [Testen von APIs gegen nicht vertrauenswürdige Eingaben](https://apidog.com/de/blog/test-api-against-untrusted-input?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).

### Sollten Validierungsfehler `400` oder `422` sein?

Verwenden Sie `400`, wenn die Anfrage syntaktisch fehlerhaft ist, etwa bei defektem JSON. Verwenden Sie `422`, wenn die Anfrage geparst werden kann, aber gegen Geschäftsregeln verstößt.

Agenten profitieren von dieser Trennung, weil die Korrekturen unterschiedlich sind. Wenn Ihre API bereits denselben Statuscode für beide Fälle verwendet, dokumentieren Sie das Verhalten, statt es ohne Migrationsplan zu ändern.

### Wie viele Details sind zu viele?

Hören Sie auf, sobald der Aufrufer genug Informationen zum Handeln hat. Feldname, Regel und ein Beispielwert reichen normalerweise aus.

Interne Identifikatoren, Abfragetext und Stack-Frames überschreiten diese Grenze.

### Werden Fehlermeldungen im Kontextfenster berücksichtigt?

Ja. Ein ausführlicher Fehler, der bei jedem Wiederholungsversuch erneut eingebettet wird, summiert sich schnell. Halten Sie Fehlerantworten auf wenige hundert Tokens begrenzt.

Der Leitfaden zum [Kürzen von API-Antworten für Agenten](https://apidog.com/de/blog/agent-tool-response-context-window?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) gilt für Fehler genauso wie für Erfolgsantworten.

### Wie verhindere ich, dass ein Agent einen nicht wiederholbaren Fehler erneut sendet?

Setzen Sie `retryable: false`, weisen Sie in `next_action` ausdrücklich darauf hin und erzwingen Sie die Regel zusätzlich im Tool-Wrapper. Die Einschätzung des Modells sollte nicht die einzige Schutzmaßnahme sein. Doppelte Absicherung ist hier sinnvoll.

Zum Testen Ihrer Fehlerformen können Sie [Apidog herunterladen](https://apidog.com/download?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).