Introduction
HTTP status codes are 3-digit codes returned in an HTTP response to indicate the status of the requested operation. They form an essential part of the HTTP protocol used on the web and in APIs. Understanding status codes is important for developers and testers when debugging issues and validating system behavior.
In this guide, we will take a deep dive into HTTP codes status, covering what they mean, how they are structured, common codes you may encounter and how to leverage them effectively.
What are HTTP Status Codes or HTTP Response Codes?
Every HTTP response returns a status code – a 3-digit integer that gives the client information about how the request was handled by the server. For example, the very common status code 200 means everything was successful, while 404 indicates a requested resource could not be found on the server.
Status codes belong to five classes based on the digit –
1xx – Informational 2xx – Success
3xx – Redirection 4xx – Client Error 5xx – Server Error
The first digit defines the class, while the last two digits provide a more specific status. Codes like 200, 404 or 500 are universally recognized on the web.
HTTP Status Code Structure
HTTP status codes follow a common structure:
- The first digit defines the class (as explained above).
- The last two digits do not have any categorization. They are used to provide a unique specific status code for different scenarios.
- Status codes are tied to a reason phrase e.g. “Not Found”, “Internal Server Error” etc. This provides a human-readable description of the status.
- Official guidelines govern the assignment of status codes to ensure standardization. New codes undergo a review process before getting added.
- APIs commonly leverage custom status codes for application-specific logic while staying within the guidelines.
By looking at the status code, both humans and machines can broadly understand the outcome of a request. The class indicates the basic nature of the response, while the exact code shows the detail.
2xx – Success Codes
The most commonly seen status codes are the success codes of the 2xx class:
- 200 OK – The standard response for a successful HTTP request. The requested resource is returned in the response. This is used after GET, PUT, PATCH or DELETE to indicate success.
- 201 Created – The request was successful and a resource was created. Used for POST requests when a new resource is added.
- 204 No Content – The request succeeded but there is no content to return in the response body.
- 206 Partial Content – Indicates a partial response. The server is returning a paginated portion of a larger resource.
- 207 Multi-Status – For batch/multi-status requests, this indicates multiple independent actions were successful.
Success codes indicate the request achieved its desired objective. 200 is the standard code you want to see for most API calls.
3xx – Redirection Codes
The 3xx class indicates the client is being redirected to another endpoint:
- 301 Moved Permanently – The requested resource has been permanently moved to a new URL. Future requests should go to the new URL.
- 302 Found – The resource is temporarily available at a different URL as specified in the Location header.
- 303 See Other – The client should retrieve the resource using a GET request to the URL in the Location header.
- 304 Not Modified – Indicates the client has the response cached. Useful for efficient caching mechanisms.
- 307 Temporary Redirect – Resource temporarily relocated to a different URL. Future requests should still use the original URL.
Redirection is useful when resources change location. Clients are expected to automatically follow 3xx redirects. 301 vs 307 status is based on permanence of the redirect.
4xx – Client Error Codes
4xx codes indicate a client-side error prevented request completion:
- 400 Bad Request – Generic error for malformed requests with syntax errors, invalid parameters etc.
- 401 Unauthorized – Authentication failed or required but missing.
- 403 Forbidden – Server refuses to authorize the request due to lack of permissions.
- 404 Not Found – The requested resource does not exist on server.
- 405 Method Not Allowed – Requested HTTP method is not supported for the URL.
- 429 Too Many Requests – Client has exceeded the request rate limit. Retry after the retry-after period.
4xx errors should be handled by the client and generally do not get automatically retried. 400 vs 404 determines if request was malformed versus resource not found.
5xx – Server Error Codes
5xx codes indicate an error on the server prevented request fulfillment:
- 500 Internal Server Error – Generic server-side error. Something unexpected went wrong on server.
- 501 Not Implemented – Server does not support the requested functionality.
- 503 Service Unavailable – Server is temporarily overloaded or down for maintenance. Try again later.
- 504 Gateway Timeout – Proxy or gateway server timed out waiting for upstream response.
- 507 Insufficient Storage – Server cannot store something due to lack of space.
5xx codes usually indicate temporary conditions that can be resolved without client changes. Clients can retry the same request after a delay. Robust clients implement retry mechanisms for 5xx errors.
Using Status Codes Effectively
Here are some best practices around HTTP status codes:
- Use specific codes – Avoid generic errors like 500 as much as possible. Pick status codes that accurately indicate the result.
- Implement error handling – Have fallback error handling middleware that converts thrown exceptions into appropriate 5xx codes.
- Follow conventions – Stick to industry conventions for popular status codes whenever possible for consistency.
- Use ranges – Reserve part of the last two digits in each class for custom app-specific codes.
- Document thoroughly – List status codes exposed by your API with detailed descriptions in the documentation.
- Handle redirects – Follow 3xx redirects instead of treating them as errors to avoid issues.
- Retry failed requests – For retries, differentiate between temporary 5xx errors versus permanent 4xx errors.
- Monitor statuses – Collect metrics on response codes to identifyfrequent errors and bugs.
Using HTTP status codes correctly goes a long way in creating APIs that are easy for clients to understand and consume.
Frequently Asked Questions
What is the most common status code?
200 OK is the standard status code returned for successful HTTP requests.
When should I use a 3xx redirect?
Use 3xx codes when resources have moved and you want clients to access them from a new endpoint from now on.
What is the difference between 400 and 404 errors?
400 means the request itself was malformed, while 404 indicates the requested resource does not exist or could not be found.
When should I retry failed requests?
5xx errors generally indicate temporary server issues and can be retried. 4xx client errors need to be fixed instead of retried.
Can I create custom status codes?
Yes, custom application-specific codes can be created by following the standard numbering scheme.
Conclusion
HTTP status codes are an essential part of APIs, conveying important information to consumers of the service. Codes are structured into classes and numbers that convey specific results. Servers should use appropriate status codes, while clients have to handle them correctly. Standard practices around testing, documentation, monitoring and handling redirects, errors and retries based on status codes greatly improve API quality and usability. I hope this guide gave you a firm understanding of the role HTTP response codes play in API messaging!
