HTTP Status Codes

HTTP status codes are three-digit numeric responses returned by web servers to indicate the result of a client's request. Every HTTP response includes a status code that tells the client whether the request succeeded, failed, was redirected, or requires additional action. Understanding HTTP status codes is essential for API development, debugging web applications, implementing proper error handling, and ensuring robust client-server communication.

HTTP status codes are defined by RFC 7231 and other HTTP specification documents. They are divided into five categories based on the first digit: 1xx Informational (request received, continuing process), 2xx Success (request was successfully received and processed), 3xx Redirection (further action needed to complete request), 4xx Client Error (request contains bad syntax or cannot be fulfilled), and 5xx Server Error (server failed to fulfill a valid request).

Why HTTP Status Codes Matter

Proper HTTP status code usage is critical for API design and web development. APIs must return the correct status code to communicate outcomes to clients: 200 OK for successful requests, 201 Created for resource creation, 404 Not Found for missing resources, 400 Bad Request for invalid input, 401 Unauthorized for authentication failures, and 500 Internal Server Error for unexpected failures.

Search engines rely on status codes for crawling and indexing. 404 indicates removed content (drop from index), 301 Moved Permanently signals a permanent redirect (transfer SEO value to new URL), 302 Found is a temporary redirect (keep original URL in index), and 410 Gone means content is permanently deleted (stronger than 404 for SEO). Incorrect codes confuse crawlers and hurt rankings.

Front-end applications use status codes for error handling logic. A 401 response triggers user re-authentication, 429 Too Many Requests implements rate limiting backoff, 503 Service Unavailable triggers retry with exponential backoff, and 422 Unprocessable Entity displays validation errors to users. Without correct codes, clients cannot implement appropriate error recovery.

Common HTTP Status Codes Explained

200 OK is the standard success response. Use for GET requests that return data, POST requests that process without creating resources, PUT/PATCH updates, or any successful operation where more specific 2xx codes don't apply. Most API responses are 200.

201 Created indicates successful resource creation. Use for POST requests that create new resources (users, posts, orders). Include a Location header with the new resource URL: 'Location: /api/users/123'. REST APIs should use 201 instead of 200 for creation endpoints.

204 No Content means success but no response body. Use for DELETE operations, PUT updates where returning updated data is unnecessary, or any successful operation where the client doesn't need response content. Reduces bandwidth for operations that don't require data back.

400 Bad Request indicates malformed or invalid client requests. Use for invalid JSON syntax, missing required fields, type errors (string instead of number), or any request the server cannot parse. Return error details in response body to help clients fix issues.

401 Unauthorized means authentication is required or failed. Use when the request lacks credentials, tokens are expired, or authentication fails. Include WWW-Authenticate header with authentication challenge. Despite the name, 401 is for authentication (who you are), not authorization.

403 Forbidden means authenticated but not authorized. Use when the user is logged in but lacks permissions for the requested resource or action. For example, a regular user trying to access admin endpoints. 403 is for authorization (what you can do), not authentication.

404 Not Found means the requested resource doesn't exist. Use for invalid URLs, deleted resources, or IDs that don't exist in the database. Don't use 404 for authorization failures - that leaks information about resource existence. Use 403 or 404 consistently for security.

500 Internal Server Error indicates unexpected server failures. Use for unhandled exceptions, database connection failures, or any error that isn't the client's fault. Never expose stack traces or sensitive error details in production. Log details server-side and return generic error messages.

HTTP Status Code Best Practices

Always return the most specific status code that matches the situation. Use 201 for creation, not generic 200. Use 422 for validation errors, not generic 400. Clients rely on specific codes for proper error handling and retry logic.

Include descriptive error messages in response bodies for 4xx and 5xx errors. Status codes tell clients what went wrong, error messages explain why and how to fix it. Example: 400 Bad Request with body: {"error": "Missing required field: email"}.

Never use 200 OK for error responses with error objects in the body. Some APIs return {"status": "error", "message": "failed"} with 200 status - this breaks HTTP semantics and confuses client error handling. Use appropriate 4xx or 5xx codes for errors.

Status Codes for RESTful APIs

REST APIs should follow HTTP semantics strictly:

• GET: 200 OK (success), 404 Not Found (doesn't exist)
• POST: 201 Created (new resource), 200 OK (processed), 400 Bad Request (invalid), 409 Conflict (duplicate)
• PUT: 200 OK (updated), 204 No Content (updated), 404 Not Found (doesn't exist), 400 Bad Request (invalid)
• PATCH: 200 OK (updated), 204 No Content (updated), 400 Bad Request (invalid)
• DELETE: 204 No Content (deleted), 200 OK (deleted with info), 404 Not Found (already gone or never existed)

Consistent status code usage makes APIs intuitive and predictable for developers.