HTTP Status Code Picker
Not sure which HTTP status code to return? Answer a few questions and this interactive decision tree will find the right one for your API response.
What is an HTTP Status Code Decision Tree?
An HTTP status code decision tree is an interactive guide that walks you through a series of questions about your API response scenario and narrows down to the single most appropriate status code. The HTTP specification defines over 60 status codes across five classes — 1xx informational, 2xx success, 3xx redirection, 4xx client error and 5xx server error — and choosing the wrong one is one of the most common API design mistakes. Using 200 for an error, 500 for a validation failure, or 404 when you mean 403 all lead to broken client integrations.
Consistent, semantically correct status codes are a hallmark of a well-designed REST API. They allow HTTP clients, API gateways, monitoring tools and load balancers to make automatic decisions about retries, caching and alerting based entirely on the status code — without parsing the response body. Getting them right the first time saves debugging time for every team that integrates with your API.
When to Use This Tool
- API design: Use the tree when you're implementing a new endpoint and aren't sure whether to return 200, 201, 202 or 204 for successful operations with different side effects.
- Code review: Check that a PR uses the right status codes for error branches — especially distinguishing 400 vs 422, and 401 vs 403.
- Debugging integration issues: When a client is behaving unexpectedly, verify whether the server is returning the correct status code for the situation rather than a catch-all 200 or 500.
- Documentation: Use this as a reference when writing API docs to ensure the status codes you're documenting actually match the intended semantics.
How It Works
The decision tree works through a branching set of yes/no questions about your API scenario: whether the request succeeded, whether it was a redirect, what kind of error occurred, and whether the error was caused by the client or the server. Each branch leads to one or two candidate status codes with a description of when that code applies and how clients are expected to interpret it. The result tells you both the right code and the reason, so you can explain the choice to a code reviewer or document it in your API spec.
Frequently Asked Questions
What is the difference between HTTP 401 and 403?
401 Unauthorized signals that the request lacks valid authentication credentials — the server doesn't know who the caller is. The response should include a WWW-Authenticate header telling the client how to authenticate. 403 Forbidden signals that the server knows who the caller is but refuses to grant access — the resource exists but the caller doesn't have permission to see it. A common security pattern is to return 404 Not Found instead of 403 when you want to conceal the existence of a resource from unauthorized callers.
When should I use 422 instead of 400?
Use 400 Bad Request when the request itself is malformed at the protocol or format level — the JSON body is unparseable, a required header is absent, or the content type is wrong. Use 422 Unprocessable Content when the request is syntactically correct but fails business logic validation — the JSON parses fine but a field value violates a constraint, such as an end date earlier than a start date, a price below zero, or a username that's already taken. This distinction helps API clients distinguish between "fix your serialisation code" (400) and "fix your input data" (422).
What is the difference between 301 and 302 redirects?
301 Moved Permanently tells the client (and search engines) that the resource has permanently moved to the new URL — the client should update any bookmarks and search engines should transfer ranking signals to the new URL. 302 Found (also called "Moved Temporarily") tells the client the resource is temporarily at a different URL but will return to the original — the client should keep using the original URL for future requests. Use 308 Permanent Redirect and 307 Temporary Redirect when you also need to preserve the original HTTP method (POST stays POST) through the redirect.