TL;DR
RFC 9457 (Problem Details for HTTP APIs) ist das Standardformat für API-Fehlerantworten. Es ersetzt benutzerdefinierte Fehlerformate durch eine konsistente Struktur: Typ, Titel, Status, Details und Instanz. Die moderne PetstoreAPI implementiert RFC 9457 für alle Fehlerantworten mit korrekter Inhaltsverhandlung und Validierungsdetails.
Einleitung
Ihre API gibt einen Fehler zurück. Wie sieht die Antwort aus? Wenn Sie wie die meisten APIs sind, haben Sie Ihr eigenes Format erfunden:
{"error": "Invalid email"}
{"message": "Not found", "code": 404}
{"success": false, "errors": ["Email required"]}
Jede API hat ein anderes Fehlerformat. Clients benötigen eine benutzerdefinierte Fehlerbehandlung für jede API. Es gibt keine Standardmethode, um Fehler zu parsen, sie Benutzern anzuzeigen oder sie zum Debuggen zu protokollieren.
RFC 9457 löst dieses Problem. Es ist ein IETF-Standard, der definiert, wie APIs Fehler zurückgeben sollen. Anstatt Ihr eigenes Format zu erfinden, verwenden Sie einen bewährten Standard, den Clients bereits verstehen.
Der alte Swagger Petstore verwendete benutzerdefinierte Fehlerformate ohne Konsistenz. Modern PetstoreAPI implementiert RFC 9457 für alle Fehlerantworten und liefert strukturierte, maschinenlesbare Fehlerdetails.
In diesem Leitfaden erfahren Sie, was RFC 9457 ist, wie Sie es korrekt implementieren und wie Modern PetstoreAPI es für alle Fehlerantworten verwendet.
Das API-Fehlerproblem
Vor RFC 9457 erfand jede API ihr eigenes Fehlerformat.
Häufige Fehlerformat-Variationen
Format 1: Einfache Nachricht
{"error": "User not found"}
Format 2: Code und Nachricht
{"code": "USER_NOT_FOUND", "message": "User not found"}
Format 3: Verschachtelte Struktur
{
"success": false,
"error": {
"type": "NotFound",
"message": "User not found"
}
}
Format 4: Array von Fehlern
{
"errors": [
{"field": "email", "message": "Invalid email"}
]
}
Probleme mit benutzerdefinierten Formaten
1. Keine Konsistenz: Clients benötigen ein benutzerdefiniertes Parsing für jede API.
2. Fehlende Informationen: Manchen Formaten fehlen Fehlercodes, manchen Details, manchen beides.
3. Keine maschinenlesbare Struktur: Es ist schwierig, Fehler programmatisch zu behandeln.
4. Schlechte Internationalisierung: Fehlermeldungen sind fest in Englisch kodiert.
5. Kein Standard für Validierungsfehler: Jede API behandelt Feld-Level-Fehler anders.
Was ist RFC 9457?
RFC 9457 (veröffentlicht im Juli 2023) definiert „Problem Details for HTTP APIs“. Es ist ein IETF-Standard, der festlegt, wie APIs Fehlerantworten strukturieren sollen.
Hauptmerkmale
Standard-Medientyp: application/problem+json (oder application/problem+xml)
Konsistente Struktur: Alle Fehler folgen dem gleichen Format
Maschinenlesbar: Clients können Fehler programmatisch parsen
Erweiterbar: Sie können benutzerdefinierte Felder hinzufügen, während die Kompatibilität erhalten bleibt
HTTP-aware: Integriert sich in HTTP-Statuscodes
RFC 9457 vs. benutzerdefinierte Fehler
Benutzerdefinierter Fehler:
{"error": "Email is required"}
RFC 9457 Fehler:
{
"type": "https://petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains invalid data",
"instance": "/pets",
"errors": [
{
"field": "email",
"message": "Email is required"
}
]
}
Die RFC 9457-Version bietet:
- Fehlertyp-URL für die Dokumentation
- Menschenlesbaren Titel
- HTTP-Statuscode
- Detaillierte Erklärung
- Pfad der Anfrage, die den Fehler verursacht hat
- Feld-Level-Validierungsdetails
RFC 9457 Struktur erklärt
RFC 9457 definiert fünf Standardfelder und erlaubt benutzerdefinierte Erweiterungen.
Standardfelder
1. type (string, erforderlich)
Eine URI-Referenz, die den Fehlertyp identifiziert. Sollte auf eine menschenlesbare Dokumentation verweisen.
"type": "https://petstoreapi.com/errors/validation-error"
Wenn weggelassen, standardmäßig about:blank.
2. title (string, erforderlich)
Eine kurze, menschenlesbare Zusammenfassung des Fehlertyps. Sollte sich zwischen den Vorkommen nicht ändern.
"title": "Validation Error"
3. status (Zahl, erforderlich)
Der HTTP-Statuscode. Zur Vereinfachung enthalten, damit Clients keine Header parsen müssen.
"status": 400
4. detail (string, optional)
Eine menschenlesbare Erklärung, die spezifisch für dieses Auftreten des Fehlers ist.
"detail": "The email field must be a valid email address"
5. instance (string, optional)
Eine URI-Referenz, die das spezifische Auftreten des Fehlers identifiziert. Oft der Anforderungspfad.
"instance": "/pets/019b4132-70aa-764f-b315-e2803d882a24"
Benutzerdefinierte Erweiterungen
Sie können benutzerdefinierte Felder für zusätzlichen Kontext hinzufügen:
{
"type": "https://petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"retryAfter": 42,
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:30:00Z"
}
Wie Modern PetstoreAPI RFC 9457 implementiert
Modern PetstoreAPI verwendet RFC 9457 für alle Fehlerantworten.
Beispiel 1: Ressource nicht gefunden
GET /pets/invalid-id
404 Not Found
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/not-found",
"title": "Resource Not Found",
"status": 404,
"detail": "The requested pet does not exist",
"instance": "/pets/invalid-id"
}
Beispiel 2: Authentifizierungsfehler
GET /pets
401 Unauthorized
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/unauthorized",
"title": "Authentication Required",
"status": 401,
"detail": "Valid authentication credentials are required to access this resource",
"instance": "/pets"
}
Beispiel 3: Ratenlimit überschritten
GET /pets
429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
{
"type": "https://docs.petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:31:00Z"
}
Siehe die Dokumentation zur Fehlerbehandlung von Modern PetstoreAPI für alle Fehlertypen.
Validierungsfehler mit RFC 9457
Validierungsfehler benötigen Details auf Feldebene. RFC 9457 ermöglicht benutzerdefinierte Erweiterungen dafür.
Modern PetstoreAPI Validierungsformat
POST /pets
400 Bad Request
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains 2 validation errors",
"instance": "/pets",
"errors": [
{
"field": "name",
"message": "Name is required",
"code": "REQUIRED_FIELD"
},
{
"field": "species",
"message": "Species must be one of: DOG, CAT, BIRD, FISH, REPTILE, OTHER",
"code": "INVALID_ENUM_VALUE",
"rejectedValue": "DRAGON"
}
]
}
Wichtige Punkte
errors-Array: Enthält Validierungsdetails auf Feldebene
field: Der JSON-Pfad zum ungültigen Feld
message: Menschenlesbare Fehlermeldung
code: Maschinenlesbarer Fehlercode
rejectedValue: Der abgelehnte Wert (optional)
Dieses Format ermöglicht Clients Folgendes:
- Feld-Level-Fehler in Formularen anzeigen
- Ungültige Felder hervorheben
- Spezifische Fehlermeldungen bereitstellen
- Fehler programmatisch behandeln
Testen von Fehlerantworten mit Apidog
Apidog hilft Ihnen, die RFC 9457-Konformität zu testen.
Testfall: Validierungsfehler
// Apidog test script
pm.test("Returns RFC 9457 error format", () => {
const response = pm.response.json();
// Check required fields
pm.expect(response).to.have.property("type");
pm.expect(response).to.have.property("title");
pm.expect(response).to.have.property("status");
// Check status matches HTTP status
pm.expect(response.status).to.equal(pm.response.code);
// Check content type
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/problem+json");
});
pm.test("Validation errors include field details", () => {
const response = pm.response.json();
pm.expect(response).to.have.property("errors");
pm.expect(response.errors).to.be.an("array");
response.errors.forEach(error => {
pm.expect(error).to.have.property("field");
pm.expect(error).to.have.property("message");
});
});
Testfall: Fehlertyp-URLs
pm.test("Error type URL is accessible", async () => {
const response = pm.response.json();
const typeUrl = response.type;
// Verify type URL returns documentation
const docResponse = await pm.sendRequest(typeUrl);
pm.expect(docResponse.code).to.equal(200);
});
Migration von benutzerdefinierten Fehlerformaten
Wenn Sie benutzerdefinierte Fehlerformate verwenden, erfahren Sie hier, wie Sie zu RFC 9457 migrieren können.
Schritt 1: Content-Type-Header hinzufügen
Beginnen Sie mit der Rückgabe von application/problem+json:
Content-Type: application/problem+json
Schritt 2: Bestehende Felder zuordnen
Ordnen Sie Ihr benutzerdefiniertes Format RFC 9457 zu:
Vorher:
{
"error": "USER_NOT_FOUND",
"message": "User not found"
}
Nachher:
{
"type": "https://api.example.com/errors/user-not-found",
"title": "User Not Found",
"status": 404,
"detail": "User not found"
}
Schritt 3: Beide Formate unterstützen (Übergangszeitraum)
Verwenden Sie Inhaltsverhandlung, um beide Formate zu unterstützen:
Accept: application/json → Gibt benutzerdefiniertes Format zurück
Accept: application/problem+json → Gibt RFC 9457-Format zurück
Schritt 4: Benutzerdefiniertes Format verwerfen
Nachdem Clients migriert sind, verwerfen Sie das benutzerdefinierte Format und geben Sie RFC 9457 standardmäßig zurück.
Fazit
RFC 9457 bietet ein Standardformat für API-Fehlerantworten. Es ersetzt benutzerdefinierte Fehlerformate durch eine konsistente, maschinenlesbare Struktur, die Clients programmatisch parsen können.
Modern PetstoreAPI implementiert RFC 9457 für alle Fehlerantworten und zeigt, wie Fehler korrekt mit entsprechenden Validierungsdetails, Fehlertyp-URLs und HTTP-Statuscodes strukturiert werden.
Verwenden Sie Apidog, um die RFC 9457-Konformität zu testen, Fehlerstrukturen zu validieren und sicherzustellen, dass Ihre API korrekte Fehlerantworten zurückgibt.
FAQ
Ist RFC 9457 für REST-APIs erforderlich?
Nein, aber es ist der empfohlene Standard. Die Verwendung von RFC 9457 macht Ihre API konsistenter und für Clients einfacher zu integrieren.
Kann ich RFC 9457 mit XML verwenden?
Ja, RFC 9457 definiert sowohl JSON- (application/problem+json) als auch XML- (application/problem+xml) Formate.
Sollte ich immer alle fünf Standardfelder einschließen?
type, title und status sind erforderlich. detail und instance sind optional, werden aber für einen besseren Fehlerkontext empfohlen.
Kann ich benutzerdefinierte Felder zu RFC 9457-Antworten hinzufügen?
Ja, RFC 9457 ist erweiterbar. Sie können benutzerdefinierte Felder wie errors, retryAfter oder traceId für zusätzlichen Kontext hinzufügen.
Wie gehe ich mit Validierungsfehlern bei RFC 9457 um?
Fügen Sie ein benutzerdefiniertes errors-Array mit Feldebene-Details hinzu. Modern PetstoreAPI zeigt dieses Muster in seinen Validierungsfehlerantworten.
Worauf sollte die Fehlertyp-URL verweisen?
Sie sollte auf eine menschenlesbare Dokumentation verweisen, die den Fehlertyp, mögliche Ursachen und deren Behebung erläutert.
Muss ich HTTP-Statuscodes ändern, wenn ich RFC 9457 verwende?
Nein, RFC 9457 funktioniert mit Standard-HTTP-Statuscodes. Das Feld status in der Antwort sollte mit dem HTTP-Statuscode übereinstimmen.
Wie teste ich die RFC 9457-Konformität?
Verwenden Sie Apidog, um die Struktur der Fehlerantwort zu validieren, erforderliche Felder zu überprüfen und sicherzustellen, dass die Inhaltstypen den RFC 9457-Spezifikationen entsprechen.