Status, type en gebeurtenis scheiden
RFC 9457 definieert application/problem+json. Gebruik een stabiel probleemtype en begrijpelijke details; clients horen geen vertaalde tekst te ontleden om te beslissen. Laat een aanwezig status-veld overeenkomen met de echte HTTP-status.
| Status | HTTP-betekenis | Mogelijke behandeling |
|---|---|---|
| 400 | Onjuist verzoek | Corrigeren vóór een nieuwe poging. |
| 401 | Geldige aanmeldgegevens ontbreken | Gegevens en afgesproken mechanisme controleren. |
| 403 | Begrepen maar geweigerd | Rechten beoordelen; herhalen verleent ze niet. |
| 503 | Dienst tijdelijk niet beschikbaar | Begrensd wachten en alleen veilig herhalen. |
Foutpaden voorspelbaar maken
- Documenteer codes, formaten en verwachte behandeling. Test lege antwoorden, niet-JSON van gateways, verbroken verbindingen en timeouts.
- Valideer invoer en rechten op de server. Behandel verwachte fouten zonder onbekende storingen te verbergen; presenteer zakelijk falen niet als succes.
- Geef een bruikbare correlatiecode voor ondersteuning. Houd stacktraces, interne queries, wachtwoorden en tokens uit publieke antwoorden.
Alleen zinvol herhalen
5xx staat geen onbeperkte pogingen toe. Combineer contract, toestand, idempotentie en deadline. Meld fouten met een minimale opgeschoonde reproductie; test na herstel het oorspronkelijke geval en verwante toegangsweigeringen.
Primaire bronnen
API-fouten moeten actie sturen zonder informatie te lekken.
HTTP-status geeft een initiële categorie, maar een client heeft mogelijk een stabiel type en nuttige details nodig. RFC 9457 beschrijft een veelvoorkomende probleemstructuur; het rechtvaardigt niet het blootleggen van interne traceringen of gevoelige gegevens.
- Scheid permanente weigering, corrigeerbare invoer en tijdelijke fout.
- Documenteer het type, de status en mogelijke clientactie voor elke belangrijke fout.
- Test of reacties geen geheimen of onnodige volledige payloads bevatten.
Primaire bron: IETF RFC 9457 — Problem Details for HTTP APIs. Verwante methode: lees de praktische gids.
API-herhalingen: het hele tijdbudget tellen
Beperk het aantal oproepen en stel een globale deadline.
Fictief leervoorbeeld: de cijfers beschrijven CIE noch klanten.
Fictief model: vier oproepen tot 250 ms met wachttijden 100, 200 en 400 ms. Jitter, verbinding, wachtrijen en lokale controle ontbreken.
- Pogingen totaal
- 41 + 3
- Wachttijden samen (ms)
- 700100 + 200 + 400
- Modelbudget (ms)
- 17004 × 250 + 700
| Stap | Maximale oproep (ms) | Volgende wachttijd (ms) |
|---|---|---|
| Poging 1 | 250 | 100 |
| Poging 2 | 250 | 200 |
| Poging 3 | 250 | 400 |
| Poging 4 | 250 | 0 |
| Totaal | 1000 | 700 |
- Oproeptijd1.000
- Opgetelde wachttijd700
- Globale deadline (ms)1.500
Controles vóór een conclusie
- 1.000 + 700 = 1.700 ms overschrijdt de deadline van 1.500 ms.
- Geef de globale deadline door en voorkom dubbele effecten; timeout bewijst geen externe annulering.
Een herhalingsbudget proberen
n × T + W × (2^(n−1) − 1)
Verwante methode: lees de praktische gids.
API-fouten: typen, statussen en bewijs
De uitgebreide toelichtingen zijn in deze editie beschikbaar in het Engels.
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