Status Codes: The Feedback

How did it go?

When the server replies, the very first thing it communicates is a three-digit status code. This is the server's immediate summary of what happened to your request. Status codes are grouped into five categories by their first digit.

2xx — Success

The request was received, understood, and accepted.

• 200 OK: Everything went perfectly. The response body contains the requested data.
• 201 Created: A new resource was successfully created (typically the response to a POST). The Location header in the response often points to the new resource's URL.
• 204 No Content: Success, but there is no body to return. Common response to a DELETE or a PUT where the server doesn't need to send anything back.

3xx — Redirection

The client must take additional action to complete the request.

• 301 Moved Permanently: The resource has a new permanent URL. Browsers and search engines update their records. Use this when you rename a page forever.
• 302 Found (Temporary Redirect): Go here for now, but keep using the original URL in the future. Common for maintenance pages.
• 304 Not Modified: The client sent a conditional request (asking "has this changed since I last fetched it?") and the server says "no, use your cached copy." This saves bandwidth.

4xx — Client Error

The request was malformed or unauthorized. The problem is on the client's side.

• 400 Bad Request: The server couldn't parse or understand the request. Often caused by malformed JSON or missing required fields.
• 401 Unauthorized: Authentication is required and was not provided or is invalid. Despite the name, this means "unauthenticated."
• 403 Forbidden: The server knows who you are (you are authenticated), but you do not have permission to access this resource. This is the true "unauthorized" response.
• 404 Not Found: The resource at this URL does not exist.
• 409 Conflict: The request conflicts with the current state of the server. Common when trying to create a resource that already exists (e.g., registering with an email already in use).
• 429 Too Many Requests: The client has sent too many requests in a given time window. Rate limiting in action.

5xx — Server Error

The request was valid, but the server failed to fulfill it. The problem is on the server's side.

• 500 Internal Server Error: A generic catch-all for unexpected server-side failures — a bug, an unhandled exception, a crashed process.
• 502 Bad Gateway: A proxy or gateway received an invalid response from an upstream server. Common when a load balancer can't reach your application.
• 503 Service Unavailable: The server is temporarily unable to handle requests — overloaded or down for maintenance.
• 504 Gateway Timeout: A proxy or gateway did not receive a timely response from an upstream server. The upstream is alive but too slow.

Key Point: The distinction between 401 and 403 trips up many developers. 401 means "I don't know who you are — please authenticate." 403 means "I know exactly who you are, and you're not allowed here." Returning 403 when you mean 401 can confuse clients and break authentication flows.