REST API Request Flow Diagram with Status Codes
Every REST API request passes the same few checkpoints in the same order: who is calling, is the request well formed, what does the handler do with it, and what did the database say. The order matters. A request that fails an early check is turned away before it costs anything, and the status code tells the client which kind of problem it was and whether trying again can help.
This template follows one request from the client to the response, with each failure ending in its status code. The meanings are the ones in RFC 9110, the HTTP Semantics specification. Use it to agree on which check comes first and which code each failure maps to before anyone writes the handler.
Scroll sideways to see the whole diagram
Start from this diagram and edit it on your own board.
By continuing, you agree to the Terms of Service and Privacy Policy, including sending images of your strokes, diagram labels and similar data to providers in the United States (Cloudflare, Inc. and TypeSafe AI, Inc.) for AI conversion.
What each part does
- Client
- Whoever calls the API: a browser, an app or another service. It sends a method, a path, headers (including its credentials) and sometimes a body.
- Authenticated?
- Checks that the request carries valid credentials, such as a session cookie or a bearer token. If not, the API answers 401 Unauthorized, and RFC 9110 requires that response to include a WWW-Authenticate header that says how to authenticate. A caller who is known but not allowed gets 403 Forbidden instead, which is a second check you can add after this one.
- Input valid?
- Checks the request before any work is done: required fields, types, ranges and formats. A request that cannot be parsed at all is a 400 Bad Request. One that parses but breaks a rule, such as an end date before the start date, is commonly answered with 422 Unprocessable Content. Pick one convention and use it everywhere.
- Handler
- The code that does the work for this route: it applies the business rules, asks the database to read or write, and builds the response.
- Database
- Stores and returns the data. The handler is the only part that talks to it, so the response can hide how the data is stored.
- 401 Unauthorized
- The end of the line for a request without valid credentials. Nothing after this point has run, so nothing was changed.
- 422 Unprocessable Content
- The end of the line for a request that is understood but does not pass validation. A good body lists which fields failed and why, so the client can fix them.
- 200 OK or 201 Created
- The success response. 200 OK is the usual answer to a read or an update. A request that creates something is answered with 201 Created, and the new resource is identified by the Location header, or by the request URL if there is none.
- 404 Not Found
- The handler found no current resource for the path, for example GET /orders/42 when there is no order 42.
- 500 Internal Server Error
- An unexpected failure on the server side, such as the database being unreachable. The client did nothing wrong, so keep details out of the body and write them to your logs. When the cause is a temporary overload or maintenance, 503 Service Unavailable, with a Retry-After header, tells the client when to try again.
How a request flows
- The client sends the request with its credentials.
- The API checks the credentials. If they are missing or invalid, it answers 401 Unauthorized and stops.
- It validates the input. If the request breaks a rule, it answers 422 Unprocessable Content (or 400 Bad Request when it cannot even parse it) and stops.
- The handler runs the business logic and sends its query to the database. What the database returns decides the response.
- If the database fails unexpectedly, the API answers 500 Internal Server Error.
- If the query finds no row for the path, the handler answers 404 Not Found.
- Otherwise the result comes back and the API answers 200 OK with it, or 201 Created when the request made something new.
When to use it
- Agreeing within a team which checks run first and which status code each failure returns, before the first handler is written.
- Writing the error section of an API guide, with one line for each failure and its code.
- Debugging a client that gets the wrong code, such as a 500 where a 404 was meant, by finding which box produced it.
Common variations
Add a permission check
Insert an Allowed? diamond after Authenticated?. A caller who is known but may not do this answers 403 Forbidden. Some APIs return 404 instead so that they do not reveal that the resource exists, which RFC 9110 allows.
Handle a conflict
When a write clashes with the current state of the resource, such as a duplicate email address, answer 409 Conflict and say in the body what clashed.
Answer a delete with 204
A successful DELETE or update that returns nothing can use 204 No Content, which has no body. DELETE and PUT are idempotent, so a client may retry them after a network failure and get the same result.
Add a rate limit
Put a check before authentication or after it, and answer with the code your API documents for too many requests. 429 Too Many Requests comes from a separate specification, RFC 6585, not from RFC 9110.
Make it yours
Add the checks your API really has between the diamonds, such as a rate limit or a permission check, and give each one its own status code.
Opens this diagram as a board you can edit.
By continuing, you agree to the Terms of Service and Privacy Policy, including sending images of your strokes, diagram labels and similar data to providers in the United States (Cloudflare, Inc. and TypeSafe AI, Inc.) for AI conversion.