HTTP Status Codes Guide

1. 1xx – Informational Responses

The 1xx class of HTTP status codes represents provisional responses. They are used exclusively
during the communication handshake between an HTTP client and server. These codes do not
indicate the state of the server or request; rather, they provide intermediate information while the
request is being processed.
1.1. 100 Continue
Indicates that the initial part of the request has been received successfully, and the client may
proceed with sending the remainder of the request body. If the request has already been
completed, the client can simply ignore this response.
Typical Use Case:
When uploading large payloads (e.g., a high-resolution video), it is inefficient to send the entire
file if the server might reject it based on constraints like maximum file size.
To optimize this:
 The client sends a preliminary request with the Expect: 100-continue, asking the server if
it is acceptable to send a payload of a certain size.
 If the server responds with 100 Continue, the client proceeds with sending the file.
 If the server rejects the expectation, it may respond with 417 Expectation Failed,
preventing unnecessary data transfer.
1.2. 101 Switching Protocols (Rarely Used)
Indicates that the server understands the client’s request to switch to a different protocol and
agrees to comply. This status code is only returned when the client includes an Upgrade header
in its request, specifying the desired protocol.
Typical Use Case:
 Upgrading from HTTP/1.1 to HTTP/2 for performance benefits.
 Switching from HTTP to a secure HTTPS connection.
 Switching to entirely different protocols (e.g., HTTP to IRC), although such cases are rare and
require both the client and server to support the target protocol.
Note: While 101 Switching Protocols is valid, it is infrequently encountered in standard
API interactions.
2. 2xx – Successful Responses
The 2xx class of HTTP status codes indicates that the client’s request was successfully received,
understood, and accepted. The server’s response usually contains the requested data or
confirmation that the requested action has been completed.
Different 2xx codes reflect different types of success, depending on the method used (GET, POST, PUT,
DELETE, etc.) and whether there is content returned.
2.1. 200 OK
The most common HTTP status code. It means the request was successful, and the server has
returned the requested data or confirmation of the action performed.
 GET requests: The requested resource is returned in the response body.
 POST/PUT requests: While 200 OK is valid, it is not always the most accurate. Specifically, when
creating a new resource, 201 Created is preferable. Returning 200 OK in such cases may imply
success without confirming the creation of the resource.
2.2. 201 Created
Indicates that a new resource has been successfully created as a result of the client’s request
and typically returned after POST requests that result in the creation of an object or record
The Location header should include the URL of the newly created resource.
2.3. 202 Accepted
Indicates that the server has successfully received the request but has not yet processed it. This
status is typically used for operations that are handled asynchronously, meaning the actual
processing will occur at a later time.
Importantly, the server does not guarantee that the request will ultimately be fulfilled, only that
it has been accepted for consideration.
Note: Clients can use the Prefer header to specify how long they are willing to wait for a final
response before receiving an immediate 202 Accepted.
Typical Use Case
 Long-running operations or processes that cannot be completed immediately (e.g.,
background jobs, batch processing).
2.4. 203 Non-Authoritative Information
Indicates that the request was successful, similar to 200 OK, but indicates that some metadata
in the response headers does not originate directly from the origin server. This may occur in
cases where the headers may have been provided by a third party or a cached copy, rather than
being generated by the original source.
Typical Use Case:
 Rare in modern APIs.
 Often appears when cached data from a third-party source is returned instead of the
original server’s response.
2.5. 204 No Content
Indicates that the server has successfully processed the request but is not returning any
content.
Typical Use Case:
 For unsafe requests (e.g., PUT, PATCH, DELETE) when the state change is successful but there
is no need to send a representation back.
 Can also be used for safe requests (e.g., GET requests) when the resource exists but has an
empty representation.
2.6. 205 Reset Content
Indicates that the client should reset the view or form from which the original request was sent.
This status code is typically used to clear form data or UI elements after a successful
submission, preparing the interface for new input.
No response body is returned with this status code.
Typical Use Case:
Form submission, the server responds with 205 Reset Content, prompting the browser to
clear the form fields.
204 No Content vs 205 Reset Content:
 204 No Content: The form remains populated after submission (e.g., editing an existing
record).
 205 Reset Content: The form is cleared for new input (e.g., entering a new record).
2.7. 206 Partial Content
Indicates that the server has successfully fulfilled a client’s partial GET request for a specific
portion of a resource, rather than the entire content. This occurs when the client includes a
Range header specifying the desired byte ranges.
Typical Use Case:
 Streaming media such as video or audio, allowing clients to download small segments as
needed.
 Resuming interrupted downloads by requesting only the remaining parts of a file.
 Efficient caching and retrieval of large files by requesting specific byte ranges.
3. 3xx – Redirection
The 3xx class of status codes indicates that further action is required by the client to complete the
request.
 If the redirection involves a GET or HEAD request, the client can usually follow it automatically
without user interaction.
 For methods such as PUT or PATCH, the client should confirm the redirection with the user to
avoid unintended actions.
3.1. 300 Multiple Choices (Rarely Used)
Indicates that the requested resource has multiple available representations, and the server
cannot determine which one the client prefers.
Typical Use Case:
 The server either selects a preferred representation and responds with 200 OK or returns a
300 Multiple Choices response listing URLs for all available options.

 If a preferred option exists, the server may include its URL in the Location header, allowing
automatic client redirection.
3.2. Response Headers: 301 Moved Permanently
Indicates that the requested resource has been permanently assigned a new URI. All future
requests should be directed to this new URL.
The Location header contains the updated permanent URL, which clients should update
accordingly.
Typical Use Case:
 Preserving API compatibility after URL structure changes to prevent breaking existing client
integrations.
3.3. 302 Found (Use Alternatives When Possible)
Originally defined as "Moved Temporarily" in HTTP/1.0 and renamed "Found" in HTTP/1.1, this
status code indicates that the requested resource resides temporarily under a different URL
provided in the Location header.
However, its behavior is often ambiguous because some clients change the HTTP method from
POST to GET when following this redirect, which can lead to unintended side effects or data
loss.
Typical Use Case:
 Used to temporarily redirect clients to a different URL while retaining the original request
method is not guaranteed.
 The response may also include a hypermedia link to the new URL, similar to 301 Moved
Permanently.
Recommendation:
To avoid ambiguity and ensure consistent behavior, prefer using status codes 303 See Other,
307 Temporary Redirect, or 308 Permanent Redirect, which explicitly define whether
the HTTP method should be changed or preserved during redirection.
3.4. 303 See Other
Indicates that the server has successfully processed the original request but instructs the client
to retrieve the result from a different URL using a GET request, regardless of the HTTP method
used initially. Allowing the server to reference the resource without forcing an immediate
download of large or non-HTML content.
The Location header contains the URL of the representation, and the Entity body should
include a hypermedia link to the same URL supporting clients that cannot automatically follow
the Location header.
Typical Use Case:
 Enables the server to provide a reference to a resource without forcing the client to
download potentially large or non-HTML content immediately.
Example:
Instead of returning a PDF file directly, the server responds with a 303 See Other status,
providing a link to the PDF for the client to retrieve as needed.
3.5. 304 Not Modified
Indicates that the requested resource has not been modified since the client’s last access. The
response contains no body, similar to 204 No Content; however, 304 Not Modified is
specifically used when the client already possesses the current version of the resource. While
returning 200 OK with the full content is valid, it is inefficient as it results in unnecessary data
transfer.
When the client includes conditional headers such as If-Modified-Since with a timestamp, and
the resource remains unchanged since that date, the server should respond with 304 Not
Modified instead of retransmitting the resource.
Typical Use Case:
 Avoids redundant data transfer when the resource has not changed.
3.6. 305 Use Proxy (Rarely Used)
Instructs the client to repeat the request using a specific HTTP proxy.
Typical Use Case:
 Used when the server requires the client to use a proxy for accessing a resource.
 Rarely implemented due to inconsistent support in clients and browsers.
3.7. 306 (Unused)
An obsolete status code that was defined in an early internet draft but is no longer used in HTTP
specifications.
3.8. 307 Temporary Redirect
This status code indicates that the requested resource has been temporarily moved to a
different URL, specified in the Location header. Importantly, the client must repeat the original
request using the same HTTP method and body at the new URL.
This ensures that methods such as POST, PUT, or PATCH are preserved and not converted to
GET during redirection, addressing a common ambiguity found in 302 Found.
Typical Use Case:
 When a resource is temporarily relocated but the client must maintain the original request
method and payload to avoid unintended side effects.
 Ensures consistent request behavior and data integrity during temporary URL changes.
303 See Other vs 307 Temporary Redirect
Analogy: A scenario involving a transaction at a specific service counter:
 303 See Other: The client is directed to a different counter to perform a distinct action,
(e.g., making a payment after submitting a form) . This represents a change in the method of
interaction.
 307 Temporary Redirect: The original service counter is temporarily unavailable, and the
client is instructed to visit an alternate location to complete the exact same transaction,
preserving the original intent and process without alteration.
3.9. 308 Permanent Redirect
Indicates that the requested resource has been permanently moved to a new URL, similar to
the 301 Moved Permanently response. However, unlike 301 Moved Permanently, the
308 Permanent Redirect code preserves the original HTTP method and request body when
redirecting. This means the client must resubmit the request using the same method to the URL
specified in the Location header.
Key Differences:
 For safe HTTP methods such as GET or HEAD, the behavior of 308 Permanent Redirect
mirrors that of 301 Moved Permanently; both instruct the client to use the new URL for
the current and all future requests.
 For unsafe methods such as POST or PATCH, the 308 Permanent Redirect status
functions similarly to the 307 Temporary Redirect in preserving the request method
and body. However, unlike the temporary nature of the 307 Temporary Redirect, a
308 Permanent Redirect indicates that the new URL should be used permanently for
future requests.
4. 4xx Client Errors
The 4xx class of HTTP status codes indicates that the client has made an error in the request,
preventing the server from processing it. These errors can arise from issues such as malformed
syntax, invalid authentication, incorrect request formatting, or timing problems.
This category contains the largest number of status codes, reflecting the wide variety of client-side
errors encountered when interacting with APIs.
4.1. 400 Bad Request
This status code signifies that the server could not understand the request due to invalid syntax.
The client should not repeat the request without modification, as the server is unable to
process improperly formed requests that violate HTTP protocol standards.
Typical Use Case:
 Sent when request payloads are malformed, missing required parameters, or contain
invalid JSON/XML syntax.
 Occurs if query parameters or headers do not comply with API specifications.
4.2. 401 Unauthorized
Indicates that the client attempted to access a protected resource without valid authentication
credentials, or the provided credentials were invalid.
Common credential types include:
 Usernames and Passwords (Basic authentication).
 API keys.
 Authentication tokens.
For enhanced security, some servers respond with a 404 Not Found instead of 401
Unauthorized to conceal the existence of protected resources from unauthorized users.
However, this requires clients to be aware in advance of the expected authentication method
for the resource.
Response headers will typically include an Authentication header specifying the required
authentication scheme.
Typical Use Case:
 Returned when a client omits the Authorization header or provides incorrect credentials.
 Triggered if an expired or invalid token is submitted in API requests.
4.3. 402 Payment Request (Reserved)
Originally intended for future use, this code is currently reserved and not in common practice.
Typical Use Case:
 Reserved for scenarios involving digital payment systems or subscription-based APIs,
though rarely implemented in practice.
 4.4. 404 Not Found
Indicates that the server could not find the requested resource at the specified URL. This
typically means that the resource either does not exist or has been moved without updating the
client’s reference.
Unlike authentication errors, this status confirms that the server is reachable but the requested
content is unavailable.
Typical Use Case:
 Occurs when a client requests a URL that does not correspond to any resource on the
server.
 Commonly returned when an API endpoint or web page has been deleted, renamed, or
mistyped in the request.
 Also used by some servers to mask resources from unauthorized users instead of returning
a 401 Unauthorized status.
5. 5xx Server Error
5.1. 500 Internal Server Error
Indicates that the server encountered an unexpected condition that prevented it from fulfilling
the request. This is a generic error message used when no more specific message is suitable.
Typical Use Case:
 Unhandled exceptions or runtime errors in server-side code.
 Failures such as database connectivity issues, memory exhaustion, or other critical failures
during request processing.
5.2. 502 Bad Gateway
Indicates that the server, while acting as a gateway or proxy, received an invalid response from
an upstream server it accessed while attempting to fulfill the request.
Typical Use Case:
 Occurs in reverse proxy or load balancer scenarios when the backend server is down or
misconfigured.
 Network or DNS errors between the gateway and the upstream server.
5.3. 503 Service Unavailable
Indicates that the server is currently unable to handle the request due to temporary
overloading or maintenance. This condition is usually temporary and the server may include a
Retry-After header indicating when to try again.
Typical Use Case:
 Scheduled server maintenance windows.
 Temporary resource exhaustion due to high traffic or DDoS attacks.
 5.4. 504 Gateway Timeout
Indicates that the server, while acting as a gateway or proxy, did not receive a timely response
from the upstream server or some other auxiliary server it needed to access to complete the
request.
Typical Use Case:
 Network latency or downtime issues in backend servers.
 Slow responses from third-party APIs or services.

Authored by: Mariam Saleh

LinkedIn: Mariam Saleh