Status, Typ und Vorkommnis trennen
RFC 9457 definiert application/problem+json. Einen stabilen Problemtyp und verständliche Details verwenden; Clients sollen keine übersetzten Sätze zur Entscheidung auswerten. Ein vorhandenes status-Feld muss zum tatsächlich gesendeten HTTP-Status passen.
| Status | HTTP-Bedeutung | Mögliche Behandlung |
|---|---|---|
| 400 | Fehlerhafte Anfrage | Vor erneutem Versuch korrigieren. |
| 401 | Gültige Anmeldedaten fehlen | Nachweise und vorgesehenen Mechanismus prüfen. |
| 403 | Verstandene Anfrage wird verweigert | Rechte prüfen; Wiederholen erteilt keine Rechte. |
| 503 | Dienst vorübergehend nicht verfügbar | Begrenzt warten und nur bei Eignung wiederholen. |
Fehlerpfade vorhersehbar gestalten
- Codes, Formate und erwartete Behandlung dokumentieren. Auch leere Antworten, Nicht-JSON vom Gateway, Verbindungsabbrüche und Timeouts testen.
- Eingaben und Rechte serverseitig prüfen. Erwartete Fehler behandeln, ohne unbekannte Störungen zu verbergen; fachliches Scheitern nicht als Erfolg tarnen.
- Eine für den Support nutzbare Korrelationskennung zurückgeben. Stacktraces, interne Abfragen, Passwörter und Token aus öffentlichen Antworten entfernen.
Nur sinnvoll wiederholen
5xx erlaubt keine unbegrenzten Versuche. Vertrag, Vorgangszustand, Idempotenz und Gesamtfrist verbinden. Fehler mit minimaler bereinigter Reproduktion melden; nach Korrektur Originalfall und benachbarte Zugriffsverweigerungen erneut prüfen.
Primärquellen
API-Fehler sollten die Maßnahmen steuern, ohne Informationen preiszugeben.
Der HTTP-Status liefert eine erste Kategorie, Clients benötigen jedoch möglicherweise einen stabilen Typ und nützliche Details. RFC 9457 beschreibt eine häufige Problemstruktur; er rechtfertigt nicht die Offenlegung interner Traces oder sensibler Daten.
- Trennen Sie dauerhafte Ablehnung, korrigierbare Eingabe und temporären Fehler.
- Dokumentieren Sie Typ, Status und mögliche Client-Aktionen für jeden wichtigen Fehler.
- Testen Sie, ob Antworten keine Geheimnisse oder unnötige vollständige Nutzdaten enthalten.
Primärquelle: IETF RFC 9457 — Problem Details for HTTP APIs. Verwandte Methode: den praktischen Leitfaden lesen.
API-Wiederholungen: das gesamte Zeitbudget zählen
Fehlerregeln brauchen eine Aufrufgrenze und Gesamtfrist.
Fiktiver Lehrfall: Die Zahlen beschreiben weder CIE noch Kunden.
Fiktives Modell: vier Aufrufe bis je 250 ms und Wartezeiten 100, 200, 400 ms. Jitter, Verbindung, Warteschlangen und lokale Prüfung fehlen.
- Versuche insgesamt
- 41 + 3
- Wartezeiten insgesamt (ms)
- 700100 + 200 + 400
- Modellbudget (ms)
- 17004 × 250 + 700
| Schritt | Maximaler Aufruf (ms) | Nächste Wartezeit (ms) |
|---|---|---|
| Versuch 1 | 250 | 100 |
| Versuch 2 | 250 | 200 |
| Versuch 3 | 250 | 400 |
| Versuch 4 | 250 | 0 |
| Gesamt | 1000 | 700 |
- Aufrufzeit1.000
- Gesamte Wartezeit700
- Gesamtfrist (ms)1.500
Prüfungen vor der Einordnung
- 1.000 + 700 = 1.700 ms überschreiten die Frist von 1.500 ms.
- Gesamtfrist weitergeben und doppelte Wirkung ausschließen; Timeout beweist keinen entfernten Abbruch.
Ein Wiederholungsbudget ausprobieren
n × T + W × (2^(n−1) − 1)
Verwandte Methode: den praktischen Leitfaden lesen.
API-Fehler: Typen, Status und Nachweise
Ausführliche Hinweise stehen in dieser Ausgabe auf Englisch zur Verfügung.
Handle an error without parsing its sentence
An API client may receive a translated title, missing member or unfamiliar extension. Preserve decisions based on the documented type and HTTP status, then connect a safe action to the context.
- Compare received status and JSON status without silently replacing either.
- Test absent type, string status instead of a number, and an unknown extension.
- Separate person-facing text, business code and occurrence reference.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5