A realistic log is mostly 200s with a scattering of 404s. An incident log is mostly 500s. Both need testing, and the weighting control switches between them without changing anything else.
What you can control
- Three distributions: realistic, uniform, and an incident mode dominated by server errors.
Retry-Afterappears on 429 and 503, the two statuses where it is meaningful.- Optional structured error bodies with a machine-readable code and a request ID.
- Every status carries its class and reason phrase for building a legend or a filter.
What this is not
Reason phrases follow the RFC. Many real APIs send custom ones, so a client that matches on the phrase rather than the numeric code is fragile regardless of what this generates.
Questions
What is the difference between 401 and 403?
401 means the request was not authenticated — send credentials and try again. 403 means it was authenticated and still not allowed, so retrying will not help.
When should an API send 422?
When the request is syntactically valid JSON but semantically wrong — a missing required field or a value out of range. A 400 means the parser could not read it at all.
Why include a Retry-After header?
Because a client that backs off blindly is guessing. On a 429 or 503 the server knows how long to wait, and clients that read the header recover much faster.