Erota tila, tyyppi ja esiintymä
RFC 9457 määrittelee application/problem+json-muodon. Käytä vakaata ongelmatyyppiä ja ymmärrettävää kuvausta; asiakkaan ei tulisi päätellä toimintaa käännetystä tekstistä. Mahdollisen status-kentän tulee vastata lähetettyä HTTP-tilaa.
| Tila | HTTP-merkitys | Mahdollinen käsittely |
|---|---|---|
| 400 | Virheellinen pyyntö | Korjaa ennen uusintaa. |
| 401 | Kelvolliset tunnistetiedot puuttuvat | Tarkista tunnisteet ja sovittu menettely. |
| 403 | Ymmärretty mutta evätty pyyntö | Tarkista oikeudet; uusinta ei anna niitä. |
| 503 | Palvelu tilapäisesti poissa | Rajattu odotus ja turvallinen uusinta. |
Tee virhepoluista ennakoitavat
- Dokumentoi koodit, muodot ja käsittely. Testaa myös tyhjät vastaukset, yhdyskäytävän muu kuin JSON, yhteyskatkot ja aikakatkaisut.
- Tarkista syötteet ja oikeudet palvelimella. Käsittele odotetut virheet peittämättä tuntemattomia vikoja; älä naamioi epäonnistumista onnistumiseksi.
- Palauta tuelle sopiva korrelaatiotunniste. Pidä pinolistaukset, sisäiset kyselyt, salasanat ja tokenit poissa julkisista vastauksista.
Uusi vain perustellusti
5xx ei salli rajattomia yrityksiä. Yhdistä sopimus, tila, idempotenssi ja aikaraja. Ilmoita viasta pienellä puhdistetulla toistotapauksella; testaa korjauksen jälkeen myös läheiset käyttöoikeuskiellot.
Alkuperäiset lähteet
API-virheiden tulisi ohjata toimintaa ilman vuotoja.
HTTP-tila antaa alkukategorian, mutta asiakas saattaa tarvita vakaan tyypin ja hyödyllisiä tietoja. RFC 9457 kuvaa yleisen ongelmarakenteen; se ei oikeuta sisäisten jälkien tai arkaluonteisten tietojen paljastamista.
- Erota pysyvä kieltäytyminen, korjattavissa oleva syöte ja tilapäinen epäonnistuminen.
- Asiakirjan tyyppi, tila ja mahdolliset asiakkaan toimet kunkin tärkeän virheen osalta.
- Testaa, että vastaukset eivät sisällä salaisuuksia tai tarpeettomia täysiä hyötykuormia.
Ensisijainen lähde: IETF RFC 9457 — Problem Details for HTTP APIs. Aiheeseen liittyvä menetelmä: lue käytännön opas.
API-uusinnat: laske koko aikabudjetti
Määritä kutsuraja ja kokonaismääräaika.
Kuvitteellinen opetustapaus: luvut eivät kuvaa CIE:tä tai asiakkaita.
Kuvitteellinen malli: neljä enintään 250 ms:n kutsua ja odotukset 100, 200, 400 ms. Jitter, yhteys, jonot ja paikallinen tarkistus puuttuvat.
- Yrityksiä yhteensä
- 41 + 3
- Odotus yhteensä (ms)
- 700100 + 200 + 400
- Mallin aikabudjetti (ms)
- 17004 × 250 + 700
| Vaihe | Kutsun enimmäisaika (ms) | Seuraava odotus (ms) |
|---|---|---|
| Yritys 1 | 250 | 100 |
| Yritys 2 | 250 | 200 |
| Yritys 3 | 250 | 400 |
| Yritys 4 | 250 | 0 |
| Yhteensä | 1000 | 700 |
- Kutsuaika1 000
- Odotusaika yhteensä700
- Kokonaismääräaika (ms)1 500
Tarkistukset ennen johtopäätöstä
- 1 000 + 700 = 1 700 ms ylittää 1 500 ms:n määräajan.
- Välitä kokonaismääräaika ja estä kaksoisvaikutukset; timeout ei todista etäpään peruutusta.
Kokeile uusintojen aikabudjettia
n × T + W × (2^(n−1) − 1)
Aiheeseen liittyvä menetelmä: lue käytännön opas.
API-virheet: tyypit, tilat ja todisteet
Tämän kieliversion tarkemmat lähdekuvaukset ovat englanniksi.
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