Az RFC 9457 ("Problem Details for HTTP APIs") az IETF szabványa, amely egységes, gép által olvasható formátumot definiál a HTTP API-k hibaválaszaihoz. A probléma részleteit JSON-objektumként (vagy XML-ként) adja át a válasz törzsében, a application/problem+json médiatípus alatt, így az API-kliensek anélkül értik meg a hiba okát, hogy minden szolgáltató saját hibastruktúrát találna ki. Az RFC 7807 (2016) utódja; 2023 júliusában jelent meg Standards Track státuszban.
A HTTP státuszkódok (pl. 400 Bad Request, 403 Forbidden, 404 Not Found) önmagukban gyakran nem adnak elég információt a hibáról. Emberi felhasználóknak a böngészőbe érkező HTML-oldal még érthető, de egy gépi API-kliens számára nincs mód a hibadokumentum egységes feldolgozására, ha minden API más formátumot használ.
Az RFC 9457 erre ad megoldást: egy közös, bővíthető JSON-objektumot ("problem details" — hibadetailed leíró dokumentumot) definiál, amelybe az API a hiba típusát, címét, részleteit és egyedi előfordulását teszi. A generikus HTTP-szoftverek (proxik, gyorsítótárak, tűzfalak, terheléselosztók) továbbra is a státuszkód alapján döntenek, az API-specifikus részletek pedig a válasz törzsében, szabványos formában jelennek meg.
Például a 403 Forbidden státuszkódot használhatjuk arra, hogy jelezzük: nincs elegendő egyenleg a vásárláshoz. A hiba miértjét (és például az aktuális egyenleget) azonban csak a válasz törzsében tudjuk átadni — pontosan erre való a problem details objektum.
A hibaobjektum az alábbi, szabványos mezőkből állhat:
| Mező | Típus | Jelentés |
|---|---|---|
type |
URI-hivatkozás (string) | A hibaprobléma-típus azonosítója. Alapértelmezett értéke about:blank. |
title |
string | A hibatípus rövid, embereknek szóló összefoglalója. |
status |
szám | A szerver által generált HTTP státuszkód (tájékoztató jellegű). |
detail |
string | Az adott hiba-előfordulásra jellemző, emberi magyarázat. |
instance |
URI-hivatkozás (string) | A hiba konkrét előfordulásának egyedi azonosítója. |
Egyetlen mező sem kötelező. A type hiánya esetén a rendszer about:blank-nak tekinti, ami azt jelenti, hogy a hibának nincs többletjelentése a státuszkódon túl — ekkor a title a státuszkód szabványos szövegével (pl. "Not Found") egyezzen meg.
type URI a hibatípus elsődleges azonosítója. Lehetőleg abszolút URI legyen, és ha feloldható, HTML-dokumentációra mutasson a hiba megoldásáról.status mező csak tájékoztató: a generátornak ugyanazt a státuszkódot kell a tényleges HTTP-válaszba is tennie, nehogy a generikus HTTP-szoftverek rosszul reagáljanak.detail-t a kliensek ne elemezzék géppel (pl. reguláris kifejezéssel) — erre a problémaspecifikus bővítmények (extension) valók.HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: hu
{
"type": "https://example.com/probs/out-of-credit",
"title": "Nincs elegendő egyenleg.",
"detail": "A jelenlegi egyenleged 30, de a tétel ára 50.",
"instance": "/account/12345/msgs/abc",
"balance": 30,
"accounts": ["/account/12345", "/account/67890"]
}Itt a balance és accounts mezők a "nincs kredit" hibatípus saját bővítményei: a kliens ez alapján tudja kezdeményezni az egyenlegfeltöltést.
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Content-Language: en
{
"type": "https://example.net/validation-error",
"title": "A kérés nem érvényes.",
"errors": [
{ "detail": "must be a positive integer", "pointer": "#/age" },
{ "detail": "must be 'green', 'red' or 'blue'", "pointer": "#/profile/color" }
]
}A validációs hibák listája a errors bővítménnyel adható át; a pointer mező JSON Pointer alapján (RFC 6901) mutat a hibás mezőre a kérés törzsében. A JSON mellé az RFC XML-változatot is definiál (application/problem+xml, urn:ietf:rfc:7807 névtér).
Az RFC javaslata szerint:
403 Forbidden önmagában is érthető.Az RFC 9457 az RFC 7807-tel szemben a következőket pontosította (2023):
http-problem-types), ahová közös, újrahasznosítható hibatípus-URI-k regisztrálhatók.tag: séma) használatához, ugyanakkor a feloldható URI-ket részesíti előnyben.Új hibatípus definiálásakor és a hibaválasz generálásakor is óvatosan kell eljárni: a hibadokumentum ne fedjen fel szerverspecifikus belső részleteket (stack dump, adatbázis-szerkezet, belső üzenetek), mert ezek támadási vektorrá válhatnak. A status mező megkettőzi a HTTP státuszkódot — ha a kettő eltér, az jelezheti, hogy egy köztes elem (pl. proxy) módosította a választ, a generikus szoftverek viszont a tényleges státuszkódot veszik alapul.
Mi az az RFC 9457? Az IETF szabványa, amely egységes JSON/XML formátumot (problem details) definiál a HTTP API-k hibaválaszaihoz.
Milyen médiatípust használ?
JSON formátum esetén application/problem+json, XML esetén application/problem+xml.
Melyik RFC-t váltja fel? Az RFC 7807-et (2016) váltja fel; a hivatkozás szerint az RFC 9457 "Obsoletes: 7807".
Kötelezők a mezők?
Nem. Csak a type-nek van alapértelmezett értéke (about:blank); a többi mező opcionális, és a type jelentését bővítő egyéni mezők is megengedettek.
Mikor érdemes használni?
Amikor a 4xx/5xx státuszkód önmagában nem elég, és gép-olvasható hiba-részleteket is át kell adni a kliensnek — pl. 403 egyenleg hiba, 422 validációs hibák, 429 rate limit.