1. Introduction

Every time a client (browser, mobile app, API consumer) sends a request to a server, the server responds with an HTTP status code that informs the client of the outcome. These codes are three-digit numbers grouped into 5 major categories.

2. 1xx: Informational Responses

These codes indicate that the request has been received and the server is continuing the process. They’re rare in everyday web development but can appear in advanced protocols and streaming scenarios.

100 Continue

• The client has sent the initial headers, and the server indicates that the request body can be sent.
• Used in situations where large payloads are being sent and the client wants confirmation before proceeding.

Example: A client uploads a large file via POST. It sends headers first. The server replies with 100 Continue to say “go ahead and send the body”.

101 Switching Protocols

• Indicates the server is switching to a different communication protocol as requested by the client, such as upgrading from HTTP to WebSocket.
• The server includes the Upgrade header to confirm the new protocol.

Example: Used in real-time applications that require WebSocket communication (e.g., live chat, stock tickers).

102 Processing (WebDAV-specific)

• Signals that the server has received and is processing the request, but no response is available yet.
• Prevents timeouts on long operations such as batch processing in WebDAV APIs.

3. 2xx: Success Codes

These codes indicate that the request was successfully received, understood, and accepted. They’re the most commonly used in REST APIs and web services.

200 OK

• The standard response for successful HTTP requests.
• The response body varies depending on the request (GET returns data, PUT may return the updated resource, etc.).

Example: A GET request for a user profile returns 200 OK with the user’s data.

201 Created

• Indicates that a new resource was successfully created.
• Often used in response to POST requests.
• Should include a Location header pointing to the URL of the newly created resource.

Example: Submitting a registration form creates a new user and returns 201 with the user’s endpoint.

202 Accepted

• The request has been accepted but not yet completed.
• Often used for asynchronous operations, such as batch jobs or long-running tasks.

Example: You submit a video for encoding. The API returns 202, indicating the job was queued.

204 No Content

• The server successfully processed the request, but there’s no response body to return.
• Often used for DELETE requests or successful PUT requests with no return payload.

Example: A DELETE request to remove a user returns 204 if it succeeded silently.

206 Partial Content

• Returned when the server is delivering partial content as requested via the Range header.
• Common in video streaming or large file downloads that support resuming.

Example: A video player requests only a segment of the video file and receives 206.

4. 3xx: Redirection Codes

These inform the client that it needs to take further action (e.g., follow another URL) to complete the request.

301 Moved Permanently

• The resource has been permanently moved to a new URL.
• Clients (and search engines) should update their references.
• The new URL is given in the Location header.

Example: Redirecting from http://example.com to https://example.com.

302 Found

• Indicates a temporary redirect.
• The resource resides temporarily under a different URI.
• Browsers usually perform an automatic redirect using GET, even if the original request was POST.

Example: Redirecting users to a login page temporarily.

303 See Other

• Directs the client to fetch the result via a GET request to a different URI.
• Typically used after a POST request to avoid resubmission.

Example: After submitting a form, the server returns 303 to redirect to a success page.

304 Not Modified

• Indicates that the resource has not changed since the client last requested it.
• Used with ETag or Last-Modified headers to optimize caching.

Example: A browser requests a cached CSS file, and the server replies 304 so the file is loaded from the cache.

307 Temporary Redirect

• Similar to 302, but preserves the original HTTP method (POST remains POST).
• Ensures request behavior remains consistent.

Example: Used in service discovery, or when maintenance requires a temporary move of an endpoint.

5. 4xx: Client Error Responses

These codes indicate that the client made an error in the request. The server understood the request but couldn’t process it.

400 Bad Request

• The request was malformed or invalid.
• Common reasons: missing required fields, invalid JSON, etc.

Example: A POST request to create a user is missing the email field.

401 Unauthorized

• Authentication is required, but the client either didn’t provide credentials or they were invalid.
• The response should include a WWW-Authenticate header.

Example: Trying to access a secure API without a token.

403 Forbidden

• The client is authenticated but doesn’t have permission to perform the action.
• Unlike 401, this is a permanent denial.

Example: A user tries to access admin-only routes.

404 Not Found

• The requested resource does not exist on the server.
• Common for broken links or incorrect URLs.

Example: Accessing /user/9999 when user 9999 doesn’t exist.

405 Method Not Allowed

• The requested HTTP method is not supported for the given resource.
• The Allow header specifies supported methods.

Example: Sending a POST to a read-only GET endpoint.

408 Request Timeout

• The client took too long to send the request.
• Could be due to slow connection or inactivity.

Example: A user begins uploading a file but doesn’t send the entire body in time.

409 Conflict

• There’s a conflict with the current state of the server.
• Common in concurrent updates or duplicate entries.

Example: Creating a user with a username that already exists.

429 Too Many Requests

• The client has sent too many requests in a given timeframe.
• Often used in rate limiting to protect against abuse.

Example: A user hits an API 500 times in one minute, exceeding the limit.

6. 5xx: Server Error Responses

These indicate that the server encountered an unexpected condition that prevented it from fulfilling the request.

500 Internal Server Error

• A generic server error.
• The server failed to fulfill the request due to an unexpected condition.
• Always indicates a problem on the server side.

Example: A null pointer exception occurs while processing a request.

501 Not Implemented

• The server doesn’t support the functionality required to fulfill the request.
• Used when a request method is recognized but not supported.

Example: The client sends a PATCH request, but the server only supports GET and POST.

502 Bad Gateway

• A gateway or proxy received an invalid response from the upstream server.
• Common in reverse proxy setups.

Example: NGINX can’t connect to a backend API that’s down.

503 Service Unavailable

• The server is temporarily unable to handle the request due to overload or maintenance.
• Often includes a Retry-After header.

Example: A site under heavy traffic returns 503 to throttle requests.

504 Gateway Timeout

• A gateway or proxy server timed out while waiting for a response from an upstream server.

Example: An API gateway waits 30 seconds for a microservice that never responds.