Card 08/ 08
Recap: Error Responses
One standard shape, a code a program can trust, every invalid field at once, and nothing an attacker can use.
An error is the part of the contract a client handles most carefully.
- One shape for every endpoint, written into the contract per operation.
- Problem details gives it:
type,title,status,detail,instance, asapplication/problem+json. - Branch on
type, never on the message, and never change a published type. - Report every invalid field at once, each with a JSON Pointer.
- Retry transient errors, 429, 503 and 504, when the request is safe to repeat; never 400, 404 or 422.
- Leave out stack traces, SQL, paths and versions; give a request ID and log the rest.
| Question | Rule |
|---|---|
| What shape? | RFC 9457 problem details, for every endpoint |
| What does a program compare? | The type URI |
| Several invalid fields? | One 422 listing each, with a pointer |
| Should the client retry? | Only transient errors, and only safe requests |
| What does a 5xx body hold? | A generic title and a request ID, nothing internal |
← → move through sections and cards