HTTP Status Codes Reference
Which Status Code Should I Return?
Use this decision tree for common REST API scenarios. Click any answer to jump to its full reference.
Did the request succeed?
YES
Did it create a new resource?
YES
201 Created
NO
Is there a response body?
YES
200 OK
NO
204 No Content
NO
Is it the client's fault?
YES
Is the user authenticated?
NO
401 Unauthorized
YES
Do they have permission?
NO
403 Forbidden
YES
Does the resource exist?
NO
404 Not Found
YES
Is the request body valid?
NO
400 Bad Request
YES
Rate limited?
YES
429 Too Many Requests
NO
409 Conflict
NO — Server error
Is it a known, temporary issue?
YES
503 Service Unavailable
NO
500 Internal Server ErrorHow to Use This Reference
This reference covers every standard HTTP status code defined in RFC 9110 and common extensions. Each entry includes the official name, a developer-friendly description, when to use it in your API, common causes, and an example response.
Use the search bar to filter by code number (e.g., 404) or keyword (e.g., redirect, cache, auth). Click the category buttons to filter by class. Click the copy button on any code to copy its number and name to your clipboard.
The decision tree above helps you choose the correct status code for common REST API scenarios — start at the top and follow the yes/no branches to find the right code.
Frequently Asked Questions
What is the difference between 401 and 403 HTTP status codes?
401 Unauthorized means the client has not provided valid authentication credentials — the server doesn't know who you are. 403 Forbidden means the server knows who you are (you're authenticated) but you don't have permission to access the requested resource. Use 401 when login is needed, and 403 when the user is logged in but lacks the required role or permissions.
When should I use 200 OK vs 201 Created vs 204 No Content?
Use 200 OK for successful GET, PUT, or PATCH requests that return data. Use 201 Created when a POST request successfully creates a new resource — include a Location header pointing to the new resource. Use 204 No Content for successful DELETE requests or updates where no response body is needed.
What does a 502 Bad Gateway error mean?
A 502 Bad Gateway means an intermediary server (like a reverse proxy, load balancer, or CDN) received an invalid response from the upstream server. Common causes include the upstream server being down, timing out, or returning a malformed response. Check your origin server's health and logs to resolve this.
What is the difference between 301 and 302 redirects?
301 Moved Permanently tells clients and search engines that the resource has permanently moved — browsers and crawlers will cache this and update their references. 302 Found indicates a temporary redirect — the original URL is still valid and clients should continue using it for future requests. Use 301 for URL migrations and 302 for temporary maintenance.
What HTTP status code should I return for validation errors?
Return 400 Bad Request for validation errors in API requests. This covers malformed JSON, missing required fields, invalid field values, and type mismatches. Include a descriptive error body with details about which fields failed. Some APIs use 422 Unprocessable Entity specifically for semantic validation errors where the syntax is correct but the values are invalid.