HTTP status codes are the core feedback mechanism in client-server communication, appearing as three-digit numbers in the HTTP response headers, revealing the result of the request processing. Understanding these status codes is crucial for developers during debugging, operations troubleshooting, or API design. This article systematically analyzes common HTTP status codes and their application scenarios, helping you quickly locate issues and optimize web services.
1. 1xx (Informational Response): Request Received, Continuing Process
These status codes indicate temporary responses, typically used for handshakes or protocol upgrades.
-
100 Continue After the client sends the Expect: 100-continue request header, if the server agrees to process, it returns this status code. The client can then send the complete request body (e.g., verifying permissions before uploading a large file).
-
101 Switching Protocols Returned when the server agrees to switch protocols via the Upgrade header (e.g., WebSocket), commonly seen in scenarios upgrading from HTTP to WebSocket.
-
102 Processing (WebDAV) indicates that the server has received the request but has not yet completed processing, preventing the client from timing out due to long wait times.
2. 2xx (Success): Request Successfully Processed
2xx status codes indicate successful operations, but the response content can vary significantly across different scenarios.
-
200 OK The most common success status code, returning resources for GET requests and operation results for PUT/POST. Note: Even if the resource is unchanged (e.g., duplicate submissions), it may still return 200.
-
201 Created Returned when a resource is successfully created via POST/PUT, with the response header including the Location field pointing to the new resource address (e.g.,
<span>/users/123</span>). -
202 Accepted The request has been accepted but not yet completed, suitable for asynchronous tasks (e.g., video transcoding). The client needs to poll or use other methods to obtain the final result.
-
204 No Content The server successfully executed the request but has no content to return, commonly seen in DELETE requests or form submissions that do not require redirection.
-
206 Partial Content Responds with partial content, used with the Range header to implement breakpoint resume or segmented downloads. This status code is commonly used by video streaming sites.
3. 3xx (Redirection): Resource Location Changed, Further Action Required
3xx status codes guide the client to a new location, but different types of redirection have varying impacts on SEO and caching.
-
301 Moved Permanently The resource has been permanently moved, and search engines will update their index. For example, after a domain change, the old link should return 301 pointing to the new address.
-
302 Found Temporary redirection, the client should continue to use the original URL to make requests. Commonly seen in short-term maintenance page redirects.
-
304 Not Modified The client cache is valid, and the server returns this status code after verifying with If-Modified-Since or ETag, significantly reducing bandwidth consumption.
-
307 Temporary Redirect Similar to 302, but it requires the client to maintain the request method (e.g., a POST request will not be changed to GET).
-
308 Permanent Redirect Similar to 301, it also requires maintaining the original request method.
4. 4xx (Client Error): Request Contains Syntax Error or Cannot Be Completed
4xx errors are usually caused by improper client requests or permission issues.
-
400 Bad Request General client error, such as JSON format errors or missing required parameters. It is recommended to provide a specific error description in the response body (e.g.,
<span>{"error": "Invalid birth_date format"}</span>). -
401 Unauthorized Not authenticated (e.g., missing JWT token). It should be accompanied by the WWW-Authenticate header to explain the authentication method.
-
403 Forbidden Authentication succeeded but access is denied (e.g., a regular user accessing an admin interface). The difference from 401 is whether authentication has occurred.
-
404 Not Found The resource does not exist, possibly due to an incorrect URL or the resource has been deleted. A friendly 404 page can enhance user experience.
-
409 Conflict The request conflicts with the current resource state (e.g., attempting to create a user with a duplicate name). The client needs to handle this and retry.
-
429 Too Many Requests The request rate limit has been exceeded, and the Retry-After header should indicate the retry time. This is commonly used for API rate limiting.
5. 5xx (Server Error): Server Failed to Process Request
5xx errors indicate server-side failures, requiring timely intervention from operations personnel.
-
500 Internal Server Error General server error, possibly due to code exceptions or configuration errors. Detailed logs should be recorded for troubleshooting.
-
502 Bad Gateway The gateway or proxy server received an invalid response from the upstream server (e.g., the backend service connected by Nginx crashed).
-
503 Service Unavailable The server is temporarily unavailable (e.g., maintenance or overload). The Retry-After header can indicate the recovery time.
-
504 Gateway Timeout The gateway server failed to receive a timely response from the upstream service (e.g., database query timeout).
6. Key Considerations
-
Status Code ≠ Error Code For example, 204 is used for successful deletion operations, and 304 indicates the cache is valid, neither of which are errors.
-
API Design Standards RESTful APIs should use status codes accurately: return 201 for resource creation, 204 for successful deletion, and still return 200 for an empty list query (rather than 404).
-
Risks of Custom Status Codes Although HTTP allows for extended status codes (e.g., 599), non-standard status codes may lead to client compatibility issues.
-
SEO Optimization Incorrect use of 301/302 may affect search engine rankings; temporary maintenance pages should use 503 instead of 302.
Conclusion
Mastering HTTP status codes is like having a “stethoscope” for diagnosing network communication. By using status codes appropriately, developers can build more robust API systems, and operations personnel can quickly locate faults. It is recommended to use tools (such as Chrome Developer Tools, Postman) to observe request responses in real-time, deepening the understanding of status codes.