HTTP Status Codes

HTTP Status Codes — What They Mean

HTTP status codes are three-digit numbers returned by a server in response to every HTTP request. They tell the client whether the request succeeded, failed, or requires further action. Understanding status codes is essential for debugging APIs, configuring redirects, and building robust error handling in web applications.

Status Code Categories

• 1xx Informational — Request received, processing continues. E.g., 100 Continue, 101 Switching Protocols.
• 2xx Success — Request was received, understood, and accepted. E.g., 200 OK, 201 Created, 204 No Content.
• 3xx Redirection — Further action needed to complete the request. E.g., 301 Moved Permanently, 304 Not Modified.
• 4xx Client Error — The request contains bad syntax or cannot be fulfilled. E.g., 400, 401, 403, 404, 429.
• 5xx Server Error — The server failed to fulfil a valid request. E.g., 500, 502 Bad Gateway, 503 Service Unavailable.

Most Important Status Codes for API Development

• 200 OK — Standard success response for GET, PUT, PATCH
• 201 Created — Resource was successfully created (POST)
• 204 No Content — Success with no response body (DELETE)
• 400 Bad Request — Malformed request syntax or invalid parameters
• 401 Unauthorized — Authentication required or credentials invalid
• 403 Forbidden — Authenticated but not authorised
• 404 Not Found — Resource does not exist
• 422 Unprocessable Entity — Validation errors on a well-formed request
• 500 Internal Server Error — Unexpected server-side failure

Common Mistakes When Using Status Codes

• Returning 200 for errors — Some APIs wrap all responses in 200 OK and put error info in the body. This breaks HTTP semantics and breaks client-side error handling.
• Using 404 for auth failures — Returning 404 to hide the existence of a resource is valid for security, but document it — callers should not interpret every 404 as a missing resource.
• Ignoring 429 Retry-After — When you receive a rate-limit response, always respect the Retry-After header to avoid getting your IP permanently blocked.

Frequently Asked Questions

What is the difference between 401 Unauthorized and 403 Forbidden?

401 Unauthorized means the request lacks valid authentication credentials — the server does not know who you are. 403 Forbidden means the server knows who you are but you do not have permission to access the resource. Fix 401 by providing credentials; 403 requires elevated permissions.

What does HTTP 301 vs 302 redirect mean?

301 Moved Permanently tells clients and search engines that a resource has permanently moved to a new URL — the new URL should be cached and indexed. 302 Found (Temporary Redirect) means the resource is temporarily at a different URL and the original URL should still be used in future requests.

What causes a 500 Internal Server Error?

A 500 error means the server encountered an unexpected condition that prevented it from fulfilling the request. Common causes include unhandled exceptions in application code, misconfigured server settings, database connection failures, or memory exhaustion. Check server-side error logs for the root cause.

When should an API return 422 instead of 400?

400 Bad Request is used when the request is syntactically malformed (invalid JSON, missing required headers). 422 Unprocessable Entity is appropriate when the request is well-formed but semantically invalid — for example, a field that fails business rule validation. REST APIs often prefer 422 for validation errors.

What is HTTP 429 Too Many Requests?

429 Too Many Requests indicates the client has sent too many requests in a given time window — the server is rate-limiting the caller. Responses typically include a Retry-After header indicating when the client may try again. This is commonly used in public APIs to prevent abuse.