QARMY
  1. Home
  2. Resources
  3. HTTP Status Codes

HTTP Status Codes

What each HTTP status code means, explained in detail for testers: purpose, common uses, headers and a complete request and response example. Search by number or name, filter by family and share a direct link to a code (for example #http-404).

Family 1xx Informational responses

The request was received and the process is continuing.

100
Continue

Tells the client that the server has received and is processing the headers of the initial request, and that it can go ahead and send the request body.

Explanation

  1. Client request: The client sends a request with the Expect: 100-continue header. This means it wants confirmation that the headers were received and accepted before sending the body (especially useful for large or critical requests).
  2. Server response: If the headers are acceptable, the server responds with 100 Continue and the client sends the body. If not, the server may respond with an error code (4xx or 5xx) instead of 100 Continue.

Usage example

Client request
POST /upload-file HTTP/1.1
Host: www.example.com
Content-Length: 52428800
Expect: 100-continue
Server interim response
HTTP/1.1 100 Continue

This mechanism optimizes the use of the network and of server resources when the body may be large: it prevents the client from sending large amounts of data only for the server to reject them because of problems in the headers.

Direct link to this code
101
Switching Protocols

Indicates that the server agrees to switch the communication protocol to a different one, as requested by the client.

Explanation

  1. Client request: The client sends an Upgrade header specifying the new protocol it wants to switch to, for example from HTTP/1.1 to HTTP/2 or to WebSocket.
  2. Server response: If it agrees, it responds 101 Switching Protocols and includes an Upgrade header with the protocol it is switching to.

Usage example

Client request
GET /chat HTTP/1.1
Host: www.example.com
Upgrade: websocket
Connection: Upgrade
Server response
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

A browser can ask to switch to WebSocket for a connection better suited to real-time communication. If the server supports it, it responds 101 and switches protocols.

Direct link to this code
102
Processing

An informational response used mainly in WebDAV to indicate that the server has received and is processing the request, but no final response is available yet.

Explanation

  1. Purpose: To report that the request was accepted and the server is working on it. It prevents the client from assuming the request failed for lack of an immediate response.
  2. Common use: Operations that may take a long time, such as processing large files or complex WebDAV operations with multiple sub-operations.
  3. Server response: While processing, it responds 102 to keep the client informed. When it finishes, it sends the final response with the appropriate code (200 OK, 201 Created, 4xx, 5xx, etc.).

Usage example

Client request
COPY /large-folder/ HTTP/1.1
Host: www.example.com
Destination: /backup/large-folder/
Server interim response
HTTP/1.1 102 Processing

It helps manage the client's expectations during long-running operations.

Direct link to this code
103
Early Hints

Lets the server send some response headers early, before the final response is ready. It improves page loading because the browser can start fetching critical resources (CSS, JavaScript, images) while the full response is being generated.

Explanation

  1. Purpose: To send part of the final response's headers in advance so the browser can start loading resources while it waits.
  2. Common use: To improve loading speed: with the early headers the browser starts additional connections and requests and reduces the total time.
  3. Server response: It sends 103 Early Hints with Link headers indicating resources to preload; then it keeps processing and sends the final response (for example 200 OK).

Usage example

Early response
HTTP/1.1 103 Early Hints
Link: </style.css>; rel=preload; as=style
Link: </script.js>; rel=preload; as=script
Final response
HTTP/1.1 200 OK
Content-Type: text/html

…

It lets the browser start loading important resources before receiving the full response, improving efficiency and speed.

Direct link to this code

Family 2xx Successful responses

The request was successfully received, understood and accepted.

200
OK

The client's request was successful and the server returned the requested information. It is one of the most common codes and means that everything worked correctly.

Explanation

  1. Purpose: Indicates that the request was successfully received, understood and accepted.
  2. Common use
    • Web pages: When a browser requests a page and the server finds it and delivers it correctly.
    • APIs: Indicates that the requested operation, such as retrieving data or completing an action, was carried out correctly.
  3. Response content: It usually includes the requested content in the body: HTML, JSON, XML, a file, etc.

Usage example

Web page request
GET /index.html HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 200 OK
Content-Type: text/html

<!DOCTYPE html>
<html>
  <head><title>Sample page</title></head>
  <body><h1>Hello, world!</h1></body>
</html>

A sign that the request was processed successfully and the response includes the requested content.

Direct link to this code
201
Created

The request was completed successfully and resulted in the creation of a new resource.

Explanation

  1. Purpose: Reports that the request was processed correctly and that a new resource was created on the server as a result.
  2. Common use
    • RESTful APIs: Creation operations, such as a POST to create a user, a blog post or an item in a database.
    • File uploads: When a file is uploaded and saved correctly.
  3. Response content
    • Location of the new resource: It usually includes a Location header with the URL of the created resource.
    • Representation of the resource: Sometimes it also includes a representation of the resource in the body.

Usage example

Request to create a user
POST /users HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "name": "John Smith",
  "email": "[email protected]"
}
Server response
HTTP/1.1 201 Created
Location: /users/123
Content-Type: application/json

{
  "id": 123,
  "name": "John Smith",
  "email": "[email protected]"
}

The request was successful and a new resource was created. The response includes its location and, optionally, a representation.

Direct link to this code
202
Accepted

The request was received and accepted for processing, but processing has not been completed yet. It does not guarantee it will finish successfully, only that it is in progress.

Explanation

  1. Purpose: To report that the request was accepted and that the server will process it later. Useful for operations that take time.
  2. Common use
    • Background processing: Asynchronous operations: processing a large file, starting a data import, running a background task.
    • APIs: Systems with long-running operations: generating reports, sending bulk emails, complex scripts.
  3. Response content
    • Additional information: It may include the current status or a link where the progress or result can be checked.
    • Headers: It may include Location with the URL where the status of the pending operation can be checked.

Usage example

Request to start a long-running task
POST /process-data HTTP/1.1
Host: www.example.com
Content-Type: application/json

{ "dataset": "large_data.csv" }
Server response
HTTP/1.1 202 Accepted
Location: /process-status/123
Content-Type: application/json

{
  "message": "The request was accepted and is being processed.",
  "process_id": 123,
  "status": "pending"
}

It signals that the operation is handled asynchronously and that the client can check the status later.

Direct link to this code
203
Non-Authoritative Information

The request was processed correctly, but the returned information may come from a local copy or a third party instead of the origin server: the content may have been modified by an intermediary (such as a proxy) before delivery.

Explanation

  1. Purpose: To report that the response is valid but not authoritative from the original source; it may have been modified by a proxy or another intermediary.
  2. Common use
    • Proxy servers: An intermediate proxy responds with content it modified or validated.
    • Caches: The content is served from an intermediate cache that may have altered the information.
  3. Response content: It includes the requested data, but the client should keep in mind that it does not come directly from the origin server and may not be an exact representation.

Usage example

Request to the server
GET /data HTTP/1.1
Host: www.example.com
Proxy response
HTTP/1.1 203 Non-Authoritative Information
Content-Type: application/json

{ "data": "This data may have been modified by the proxy." }

The request was completed, but the information may have been modified by an intermediary and does not come directly from the original source.

Direct link to this code
204
No Content

The request was processed correctly and the server does not need to return any content in the body. Useful when there is no need to send data to the client after a successful operation.

Explanation

  1. Purpose: To report that the request was processed successfully but there is no content to send. Suitable for operations such as updating with PUT or performing actions with DELETE.
  2. Common use
    • Update operations: After a PUT to update a resource.
    • Resource deletion: After a DELETE.
    • Operations that need no response: When the action is completed and there is no need to return data.
  3. Response content: There is no body. It may include relevant headers such as Content-Location or ETag.

Usage example

Request to update a resource
PUT /users/123 HTTP/1.1
Host: www.example.com
Content-Type: application/json

{ "name": "John Smith Updated" }
Server response
HTTP/1.1 204 No Content

The action was completed and there is no need to send additional data to the client.

Direct link to this code
205
Reset Content

The request was processed successfully and the server wants the user agent (the browser) to reset the view that caused the request: for example, clearing a form or returning the interface to its original state.

Explanation

  1. Purpose: To report that the request was completed and that the client should reset the view or the interface. Especially useful after submitting forms.
  2. Common use
    • Web forms: After a form is submitted, the server responds 205 to indicate that it should be cleared.
    • User interface: To indicate that any input or temporary state should return to its default value.
  3. Response content: The body must be empty. It may include relevant headers.

Usage example

Request to submit a form
POST /submit-form HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

firstname=John&lastname=Smith
Server response
HTTP/1.1 205 Reset Content

It ensures the interface returns to a default state after a successful operation.

Direct link to this code
206
Partial Content

The server fulfilled a GET request but returned only part of the resource. It is used when the client asks for a specific portion of a file with range headers, for partial downloads or media streaming.

Explanation

  1. Purpose: To report that the request for a specific range was successful and that only that part of the content was sent.
  2. Common use
    • Interrupted and resumable downloads: It lets downloads resume by requesting only the missing parts.
    • Video and audio streaming: The client requests specific parts of the file to play in real time.
  3. Related headers
    • Range: The client specifies the byte range it wants to receive.
    • Content-Range: The server indicates which part of the content it is returning.

Usage example

Request for part of the file
GET /video.mp4 HTTP/1.1
Host: www.example.com
Range: bytes=0-1023
Server response
HTTP/1.1 206 Partial Content
Content-Type: video/mp4
Content-Range: bytes 0-1023/10000

[first 1024 bytes of the video file]

Especially useful for large or interrupted downloads and media streaming: the client receives parts of the resource instead of downloading it in full.

Direct link to this code
207
Multi-Status

Specific to WebDAV. The response contains information about multiple resources, and each one can have a different status code.

Explanation

  1. Purpose: To report that the request affected several resources and provide a separate status code for each one. Useful when a single WebDAV request affects several files or directories.
  2. Common use
    • WebDAV operations: Responses to PROPFIND, PROPPATCH and MOVE, which can involve multiple resources.
    • Detailed results: It lets you indicate the success or failure of each resource individually.
  3. Response format: An XML document with <response>, <href> and <status> elements for each resource.

Usage example

PROPFIND request
PROPFIND /my-folder/ HTTP/1.1
Host: www.example.com
Depth: 1
Server response
HTTP/1.1 207 Multi-Status
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<multistatus xmlns="DAV:">
  <response>
    <href>/my-folder/file1</href>
    <propstat>
      <prop><displayname>file1</displayname></prop>
      <status>HTTP/1.1 200 OK</status>
    </propstat>
  </response>
  <response>
    <href>/my-folder/file2</href>
    <propstat>
      <prop><displayname>file2</displayname></prop>
      <status>HTTP/1.1 404 Not Found</status>
    </propstat>
  </response>
</multistatus>

It lets the client understand how each individual resource was affected by the request.

Direct link to this code
208
Already Reported

Specific to WebDAV. It is used inside a DAV:propstat element to avoid repeatedly enumerating the internal members of collections with multiple bindings.

Explanation

  1. Purpose: To indicate that the members of a collection (for example, the files in a directory) were already enumerated in a previous response, avoiding duplicate information.
  2. Common use
    • WebDAV operations: Responses to PROPFIND and other requests that enumerate resources in collections.
    • Duplicate prevention: It avoids redundancy when a resource was already listed in the same result set.
  3. Response format: It appears inside a 207 Multi-Status response, indicating that the resource was already reported.

Usage example

PROPFIND request
PROPFIND /my-folder/ HTTP/1.1
Host: www.example.com
Depth: 1
Server response
HTTP/1.1 207 Multi-Status
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<multistatus xmlns="DAV:">
  <response>
    <href>/my-folder/file1</href>
    <propstat><status>HTTP/1.1 200 OK</status></propstat>
  </response>
  <response>
    <href>/my-folder/file2</href>
    <propstat><status>HTTP/1.1 208 Already Reported</status></propstat>
  </response>
</multistatus>

It avoids duplicating information in the same set of responses.

Direct link to this code
214
Transformation Appliednon-standard

It is not part of the standard set of HTTP codes defined by the IETF. There are some references to it in the context of HTTP extensions, but it is not a standard code. An interpretation can be offered based on its name.

Explanation

  1. Purpose: It suggests that a transformation was applied to the response: the server modified the content in some way before sending it.
  2. Hypothetical use
    • Content transformations: To indicate that the content was compressed, resized, translated or transformed in some other way.
    • Intermediaries or proxies: Situations where a proxy or intermediate server modifies the content before delivering it.

Since it is not part of the official standards, its use is not formally defined and may vary by implementation. If you work with a system that uses it, check its documentation.

Direct link to this code
226
IM Used

Part of HTTP/1.1 according to RFC 3229, related to instance manipulations (IM).

Explanation

  1. Purpose: Indicates that the server fulfilled a GET request and that the response is the result of one or more instance manipulations applied to the current version of the resource.
  2. Common use
    • Efficient transfers: It lets the server send only the changes (deltas) since a known version of the resource instead of the full resource.
    • Methodology: It is achieved with the manipulations specified in the request's IM header; clients synchronize their copies efficiently.
  3. Context of use: Incremental updates in applications where resources change often and clients already have a copy: it reduces bandwidth and transfer time.

Usage example

Client request
GET /my-resource HTTP/1.1
Host: www.example.com
IM: delta
Server response
HTTP/1.1 226 IM Used
Content-Type: application/json
IM: delta

{
  "changes": [
    { "op": "replace", "path": "/name", "value": "New Name" },
    { "op": "add", "path": "/attributes/new_attribute", "value": "value" }
  ]
}

It reduces the amount of data transferred by sending only the differences from a known version of the resource.

Direct link to this code

Family 3xx Redirects

Further action from the client is needed to complete the request.

300
Multiple Choices

The request has more than one possible response and the user or user agent must choose one. The server offers several options so the client can select the most suitable one.

Explanation

  1. Purpose: To report that there are multiple representations of the resource and allow one to be chosen. Useful when a resource has different formats or versions.
  2. Common use
    • Different formats: The resource is available in JSON, XML or HTML and the server offers the options.
    • Language variants: The resource has versions in several languages and the client chooses the preferred one.
  3. Response content
    • List of options: It usually includes links to the different options.
    • Location header: It may include a preferred URI.

Usage example

Client request
GET /my-resource HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 300 Multiple Choices
Content-Type: text/html

<html><body>
  <h1>Multiple Choices</h1>
  <ul>
    <li><a href="/my-resource.json">/mi-recurso.json</a> (JSON)</li>
    <li><a href="/my-resource.xml">/mi-recurso.xml</a> (XML)</li>
    <li><a href="/my-resource.html">/mi-recurso.html</a> (HTML)</li>
  </ul>
</body></html>

There are multiple possible responses and the client must choose which one to use; the response provides the available options.

Direct link to this code
301
Moved Permanently

The requested resource has been moved permanently to a new URL. All future requests should be made to the new URL.

Explanation

  1. Purpose: To report that the resource is no longer at the current URL and has been moved permanently. The client should update links and bookmarks.
  2. Common use
    • Permanent redirect: When a site's URL structure changes, the domain changes or paths are reorganized.
    • SEO: It preserves search engine rankings by transferring link value (link juice) from the old URL to the new one.
  3. Response content
    • Location header: It contains the new URL.
    • Optionally, a body: It may include a message about the redirect.

Usage example

Client request
GET /old-path HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 301 Moved Permanently
Location: https://www.example.com/new-path
Content-Type: text/html

<html><body>
  <h1>The resource has been moved permanently</h1>
  <p>La nueva URL es <a href="https://www.example.com/new-path">https://www.ejemplo.com/nueva-ruta</a></p>
</body></html>

Clients and search engines should update their references to the old URL to use the new one in the future.

Direct link to this code
302
Found

The resource is temporarily at a different URL. The client should keep using the original URL in future requests, because the redirect is temporary.

Explanation

  1. Purpose: To report that the resource is temporarily in another location and that the redirect should be followed; the original URL is still valid.
  2. Common use
    • Temporary redirect: During site maintenance or for A/B testing.
    • Temporary moves: Temporarily moved resources that are expected to return to their original location.
  3. Response content
    • Location header: It contains the temporary URL.
    • Optionally, a body: It may include a message about the redirect.

Usage example

Client request
GET /original-path HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 302 Found
Location: https://www.example.com/temporary-path
Content-Type: text/html

<html><body>
  <h1>The resource has moved temporarily</h1>
  <p>Visitá la URL temporal: <a href="https://www.example.com/temporary-path">https://www.ejemplo.com/ruta-temporal</a></p>
</body></html>

The client follows the redirect but keeps using the original URL for future requests.

Direct link to this code
303
See Other

The resource is at another URL and must be retrieved with a GET request. It is typically used after processing a POST, so the client gets the information from the new URL with GET.

Explanation

  1. Purpose: Useful for redirects after unsafe operations (such as POST), where the response must be retrieved with GET.
  2. Common use
    • Redirect after a POST: After processing a form, redirect to a confirmation page with GET.
    • Preventing resubmissions: It prevents the form from being resubmitted if the user refreshes the page.
  3. Response content
    • Location header: The URL the client should be redirected to.
    • Optionally, a body: A message about the redirect.

Usage example

Client POST request
POST /submit-form HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

firstname=John&lastname=Smith
Server response
HTTP/1.1 303 See Other
Location: https://www.example.com/confirmation
Content-Type: text/html

<html><body>
  <h1>Form submitted</h1>
  <p>Redirecting to the confirmation page…</p>
</body></html>

Especially useful after a POST to redirect the client to a new page without the risk of the form being resubmitted.

Direct link to this code
304
Not Modified

The resource has not been modified since it was last accessed. The server does not need to send the content again: the client can use the version in its cache.

Explanation

  1. Purpose: To let the client use its cached copy instead of downloading the full resource, reducing bandwidth and improving performance.
  2. Common use
    • Cache control: Together with conditional headers such as If-Modified-Since or If-None-Match.
    • Efficiency: It avoids unnecessary transfers and speeds up page loading.
  3. Related headers
    • If-Modified-Since: The client sends the date of the last known modification; if it has not changed, the server responds 304.
    • If-None-Match: The client sends an ETag; if it matches the current one, the server responds 304.

Usage example

Conditional request
GET /my-resource HTTP/1.1
Host: www.example.com
If-Modified-Since: Wed, 21 Oct 2020 07:28:00 GMT
Server response
HTTP/1.1 304 Not Modified

The client uses its cached copy, improving efficiency and performance by avoiding unnecessary data transfers.

Direct link to this code
305
Use Proxynon-standard

The resource must be accessed through the specified proxy. It was deprecated because of security concerns and is no longer widely used.

Explanation

  1. Purpose: To report that a specific proxy must be used, whose address goes in the Location header.
  2. Common use
    • Redirect through a proxy: It could be used to implement access controls or route traffic through a checkpoint.
    • Deprecated: Because of security problems and the exposure of configuration details, modern browsers stopped supporting it.
  3. Response content: The Location header contains the URL of the proxy that must be used.

Usage example

Client request
GET /resource HTTP/1.1
Host: www.example.com
Server response (deprecated)
HTTP/1.1 305 Use Proxy
Location: http://proxy.example.com:8080

Deprecated: its use is no longer recommended or supported by most browsers.

Direct link to this code
307
Temporary Redirect

The resource is temporarily at another URL and the client must repeat the request to that URL with the same HTTP method. Unlike 302, it guarantees that the method and body are preserved.

Explanation

  1. Purpose: A temporary redirect that preserves the original method (GET, POST, etc.).
  2. Common use
    • Temporary redirect: To temporarily redirect to a new URL without changing the method.
    • Method preservation: It ensures that a POST does not become a GET, keeping the integrity of the data and the intent of the request.
  3. Response content
    • Location header: The temporary URL.
    • Optionally, a body: A message about the redirect.

Usage example

Client request
POST /submit-form HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

firstname=John&lastname=Smith
Server response
HTTP/1.1 307 Temporary Redirect
Location: https://www.example.com/temporary-form
Content-Type: text/html

<html><body>
  <h1>Form submitted</h1>
  <p>Temporarily redirecting to the new URL…</p>
</body></html>

Useful for temporary redirects where it is important to preserve the method of the original request.

Direct link to this code
308
Permanent Redirect

The resource has moved permanently to a new URL and the client must use it in all future requests. Unlike 301, it guarantees that the method and body are preserved.

Explanation

  1. Purpose: To report the permanent move and ensure the original method is preserved. The client should update links and bookmarks.
  2. Common use
    • Permanent redirect: When a resource has moved for good.
    • Method preservation: It ensures that a POST does not become a GET.
  3. Response content
    • Location header: The new permanent URL.
    • Optionally, a body: A message about the redirect.

Usage example

Client request
POST /submit-form HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

firstname=John&lastname=Smith
Server response
HTTP/1.1 308 Permanent Redirect
Location: https://www.example.com/new-location
Content-Type: text/html

<html><body>
  <h1>Resource moved permanently</h1>
  <p>La nueva URL es <a href="https://www.example.com/new-location">https://www.ejemplo.com/nueva-ubicacion</a></p>
</body></html>

Useful for permanent redirects where it is important to preserve the method of the original request.

Direct link to this code

Family 4xx Client errors

The request has a problem: syntax, permissions or a nonexistent resource.

400
Bad Request

The server cannot or will not process the request because of a client error: incorrect syntax, a malformed request or invalid data.

Explanation

  1. Purpose: To report that the request cannot be processed because of a problem with the data sent: syntax errors, incorrect parameters or invalid data.
  2. Common use
    • Incorrect syntax: The request contains errors and the server cannot interpret it.
    • Invalid data: The data does not meet the server's requirements.
    • Missing parameters: Not all the required parameters are included, or they are incorrect.
  3. Response content
    • Error message: It can explain the nature of the error.
    • Error details: In complex applications, additional details to correct the request.

Usage example

Request with a syntax error
GET /my-resource HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

firstname=John&lastname
Server response
HTTP/1.1 400 Bad Request
Content-Type: text/html

<html><body>
  <h1>Bad request</h1>
  <p>The request could not be processed because of a syntax error.</p>
</body></html>

It signals syntax errors, missing parameters or invalid data; it can include a message that helps the client correct the request.

Direct link to this code
401
Unauthorized

The request was not applied because it lacks valid authentication credentials for the resource. The client must authenticate to get the response.

Explanation

  1. Purpose: To report that the request cannot proceed because no credentials were provided or the ones provided are invalid.
  2. Common use
    • Authentication required: The resource requires authentication and the client did not send any credentials.
    • Invalid credentials: The credentials are incorrect or have expired.
  3. Response content: It includes the WWW-Authenticate header with the authentication method the client must use: username and password, a token or another type of credential.

Usage example

Request without authentication
GET /protected-resource HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Access to protected resources"
Content-Type: text/html

<html><body>
  <h1>Authentication required</h1>
  <p>You must authenticate to access this resource.</p>
</body></html>

The response includes WWW-Authenticate, which specifies how the client must authenticate to access the resource.

Direct link to this code
402
Payment Required

A code reserved for future use. It is not used in conventional web applications and services. Its original purpose was to indicate that access requires payment, but it was never widely standardized or implemented.

Explanation

  1. Intended purpose: To report that the request cannot be processed until a payment is made.
  2. Common use
    • Not currently in use: There is no standard implementation; it is not used by browsers or conventional APIs.
    • Future applications: It could be used for subscriptions, premium services or paid content.
  3. Response content: Any implementation would be vendor-specific and could include information on how to pay.

Usage example

Request for a premium resource
GET /premium-content HTTP/1.1
Host: www.example.com
Server response (hypothetical)
HTTP/1.1 402 Payment Required
Content-Type: text/html

<html><body>
  <h1>Payment required</h1>
  <p>Para acceder a este contenido, debe realizar un pago. Visite <a href="https://www.example.com/payment">nuestro portal de pagos</a>.</p>
</body></html>

Reserved for future use; there is currently no standard implementation.

Direct link to this code
403
Forbidden

The server understood the request but refuses to authorize it. Unlike 401, which implies missing credentials, 403 indicates that the server knows who the client is but access is forbidden.

Explanation

  1. Purpose: To report that, although the request was understood and needs no additional authentication, the server refuses to fulfill it because of access restrictions.
  2. Common use
    • Insufficient permissions: A user without administrator privileges tries to access an admin page.
    • Protected resources: Access forbidden by server settings or security policies.
    • IP blocking: Access control policies based on the IP address.
  3. Response content
    • Error message: It can explain the reason for the restriction.
    • Additional details: How to get access or whom to contact.

Usage example

Request without sufficient permissions
GET /admin HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 403 Forbidden
Content-Type: text/html

<html><body>
  <h1>Access denied</h1>
  <p>You do not have permission to access this resource.</p>
</body></html>

It may be due to insufficient permissions, security policies or server settings that forbid access.

Direct link to this code
404
Not Found

The server cannot find the requested resource: there is no page or file matching the URL requested by the client.

Explanation

  1. Purpose: To report that the resource is not available: the URL is wrong, the resource was deleted or it never existed.
  2. Common use
    • Incorrect URL: The URL does not match any resource.
    • Deleted resource: It was deleted or moved to another location.
    • Typo: The client mistyped the URL.
  3. Response content
    • Custom error page: Many sites offer additional information, useful links or a search box.
    • Basic message: Without a custom page, a message saying the page was not found.

Usage example

Request for a nonexistent resource
GET /missing-page HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 404 Not Found
Content-Type: text/html

<html><body>
  <h1>404 Not Found</h1>
  <p>The page you are looking for does not exist.</p>
</body></html>

The URL does not match any available resource; the response can include an error page that helps the user find their way.

Direct link to this code
405
Method Not Allowed

The request method is known by the server but is not allowed for the requested resource. The server recognizes the method (GET, POST, PUT, DELETE…) but does not allow it on that URL.

Explanation

  1. Purpose: To report that the HTTP method used is not allowed for the resource, because of server restrictions or the resource's configuration.
  2. Common use
    • Resource restrictions: An API allows GET and POST but not DELETE.
    • Server restrictions: Policies that limit the methods allowed on certain paths.
  3. Response content
    • Allow header: It must list the methods allowed for the resource.
    • Error message: It can explain the error.

Usage example

Request with a method that is not allowed
DELETE /resource HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 405 Method Not Allowed
Allow: GET, POST
Content-Type: text/html

<html><body>
  <h1>Method not allowed</h1>
  <p>The DELETE method is not allowed for this resource. The allowed methods are GET and POST.</p>
</body></html>

The response must include the Allow header with the allowed methods.

Direct link to this code
406
Not Acceptable

The server cannot produce an acceptable response according to the request's Accept headers: it cannot satisfy the client's content constraints.

Explanation

  1. Purpose: To report that the server cannot respond in any of the formats listed in Accept: content types, encodings, languages, etc.
  2. Common use
    • Content negotiation: The client only accepts JSON or XML and the server cannot return those formats.
    • Client constraints: Accept, Accept-Encoding, Accept-Language and Accept-Charset headers.
  3. Response content
    • Error message: It can explain why it cannot be fulfilled.
    • Alternative options: Information about the available formats.

Usage example

Request with content constraints
GET /resource HTTP/1.1
Host: www.example.com
Accept: application/json
Server response
HTTP/1.1 406 Not Acceptable
Content-Type: text/html

<html><body>
  <h1>Not acceptable</h1>
  <p>The server cannot produce a response in the requested format (application/json).</p>
</body></html>

The server cannot meet the client's content constraints; it can report the alternative formats available.

Direct link to this code
407
Proxy Authentication Required

The client must authenticate with a proxy before the request can be processed. Similar to 401, but applied to the authentication required by a proxy server.

Explanation

  1. Purpose: To report that the proxy needs authentication credentials before allowing access to the resource.
  2. Common use
    • Proxy authentication: Corporate environments or networks that use proxies to manage Internet access.
    • Network configuration: The proxy requires valid credentials before allowing traffic.
  3. Response content
    • Proxy-Authenticate header: It specifies the authentication method the client must use with the proxy.
    • Error message: It can explain that authentication with the proxy is required.

Usage example

Request without proxy authentication
GET /resource HTTP/1.1
Host: www.example.com
Proxy response
HTTP/1.1 407 Proxy Authentication Required
Proxy-Authenticate: Basic realm="Proxy"
Content-Type: text/html

<html><body>
  <h1>Proxy authentication required</h1>
  <p>You must authenticate with the proxy to access the requested resource.</p>
</body></html>

The response includes Proxy-Authenticate with the authentication method required by the proxy.

Direct link to this code
408
Request Timeout

The server did not receive a complete request within the time it was prepared to wait.

Explanation

  1. Purpose: To report that the server closed the connection because the request was not completed in a reasonable time, due to a slow connection or because the client stopped sending data.
  2. Common use
    • Slow connections: The client cannot send the complete request in time because of slowness or interruptions.
    • Server timeout: The server has a timeout configured and the request was not completed within that time.
  3. Response content: It can include a message saying the timeout expired.

Usage example

Request that is not completed in time
GET /resource HTTP/1.1
Host: www.example.com
(waiting for additional data that never arrives)
Server response
HTTP/1.1 408 Request Timeout
Content-Type: text/html

<html><body>
  <h1>Request timed out</h1>
  <p>The server did not receive the complete request within the expected time.</p>
</body></html>

It can be caused by slow connections, interruptions or anything else that prevents the request from being completed in the expected time.

Direct link to this code
409
Conflict

The request could not be completed because of a conflict with the current state of the resource. It is used when the server detects conflicts with the resource being modified or updated.

Explanation

  1. Purpose: To report that there is a conflict with the current state of the resource: a concurrent modification or data that creates a conflict.
  2. Common use
    • Editing conflicts: Several users modify the same resource at the same time.
    • State conflicts: Updating a resource with outdated data.
  3. Response content
    • Error message: It describes the conflict and, if possible, how to resolve it.
    • Conflict details: Resource versions, update suggestions, etc.

Usage example

Request to update a resource with a conflict
PUT /resource HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "id": 1,
  "name": "Updated Resource",
  "version": 1
}
Server response
HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "message": "Conflict while trying to update the resource.",
  "details": "The resource was modified by another user. Get the latest version and try again."
}

Typical in concurrent editing; the response can detail the nature of the conflict and how to resolve it.

Direct link to this code
410
Gone

The resource is no longer available and there is no known forwarding address. The server knows the resource will not be available again.

Explanation

  1. Purpose: To report that the resource was permanently deleted and there is no new URL. Unlike 404, which makes no assumptions about permanence.
  2. Common use
    • Permanent deletion: Deleted resources that will not come back online.
    • Expired content: Retired articles, documents or pages that will not be replaced.
  3. Response content: It can include a message explaining that the resource was deleted.

Usage example

Request for a deleted resource
GET /old-resource HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 410 Gone
Content-Type: text/html

<html><body>
  <h1>Resource deleted</h1>
  <p>The resource is no longer available and there is no known forwarding address.</p>
</body></html>

It signals the permanent removal and helps clients and search engines understand that they should stop requesting that resource.

Direct link to this code
411
Length Required

The server rejects the request because it does not include the Content-Length header, which is needed to process it.

Explanation

  1. Purpose: To report that Content-Length, which specifies the length of the request body, is missing.
  2. Common use: Some servers need to know the exact length of the content to handle it properly, especially in POST or PUT.
  3. Response content: It can include a message saying Content-Length is required.

Usage example

Request without Content-Length
POST /upload HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "name": "John Smith",
  "file": "data.bin"
}
Server response
HTTP/1.1 411 Length Required
Content-Type: text/html

<html><body>
  <h1>Length required</h1>
  <p>The Content-Length header is required to process this request.</p>
</body></html>

It ensures the server has the information it needs to handle the request content.

Direct link to this code
412
Precondition Failed

One or more conditions in the request headers evaluated to false on the server, which therefore will not fulfill the request.

Explanation

  1. Purpose: To report that the conditions of headers such as If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since or If-Range are not met.
  2. Common use
    • Conditional headers: To make sure a resource has not been modified since a given date or that it matches an ETag.
    • Concurrency control: To avoid conflicts when several clients modify a resource at the same time.
  3. Response content: It can explain why the conditions were not met.

Usage example

Request with conditions
PUT /resource HTTP/1.1
Host: www.example.com
If-Match: "etag12345"
Content-Type: application/json

{ "name": "Updated Resource" }
Server response
HTTP/1.1 412 Precondition Failed
Content-Type: text/html

<html><body>
  <h1>Precondition failed</h1>
  <p>The condition specified in the If-Match header was not met.</p>
</body></html>

It makes it possible to handle conditional requests and avoid conflicts where concurrency or version control rules apply.

Direct link to this code
413
Payload Too Large

The request is larger than the server is willing or able to process, so it was rejected.

Explanation

  1. Purpose: To report that the request body exceeds the size the server can handle.
  2. Common use
    • Excessive payload size: Uploading a file or sending data that exceeds the limit.
    • Server configuration: Maximum limit configured for request bodies.
  3. Response content
    • Error message: It can explain that the body is too large.
    • Retry-After header (optional): It can indicate when to retry or give additional instructions.

Usage example

Request with a body that is too large
POST /upload-file HTTP/1.1
Host: www.example.com
Content-Type: application/octet-stream
Content-Length: 52428800

[file data]
Server response
HTTP/1.1 413 Payload Too Large
Content-Type: text/html

<html><body>
  <h1>Payload too large</h1>
  <p>The server cannot process the request because the body is too large.</p>
</body></html>

The size of the data sent exceeds the server's limits.

Direct link to this code
414
URI Too Long

The request URI is too long for the server to process: it exceeds the limit the server is willing to handle.

Explanation

  1. Purpose: To report that the URI is too long, for example because of excessive query parameters.
  2. Common use
    • Automatically generated URIs: Systems that generate URIs with large amounts of data or parameters.
    • Configuration errors: A client application builds a URI that exceeds the limits.
  3. Response content: It can include a message explaining that the URI is too long.

Usage example

Request with a URI that is too long
GET /search?param1=value1&param2=value2&…&param1000=value1000 HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 414 URI Too Long
Content-Type: text/html

<html><body>
  <h1>URI too long</h1>
  <p>The URI provided is too long to be processed by the server.</p>
</body></html>

Also known as Request-URI Too Long. The length of the URI exceeds the allowed limits.

Direct link to this code
415
Unsupported Media Type

The server rejects the request because the content type of the body is not supported for the requested resource.

Explanation

  1. Purpose: To report that the media type of the body is not compatible with the resource.
  2. Common use
    • Unsupported content type: Sending XML to an endpoint that only accepts JSON.
    • Incorrect Content-Type: The header specifies a type the server cannot handle.
  3. Response content: It can explain that the content type is not supported.

Usage example

Request with an unsupported content type
POST /api/resource HTTP/1.1
Host: www.example.com
Content-Type: application/xml

<resource>
  <name>Example</name>
</resource>
Server response
HTTP/1.1 415 Unsupported Media Type
Content-Type: text/html

<html><body>
  <h1>Unsupported media type</h1>
  <p>The server cannot process the request because the content type 'application/xml' is not supported.</p>
</body></html>

The media type of the body is not compatible with the resource; the response can help fix the problem.

Direct link to this code
416
Range Not Satisfiable

The server cannot fulfill the range specified in the Range header: the requested range is not valid for the size of the resource.

Explanation

  1. Purpose: To report that the requested part of the resource cannot be provided because the range is not valid.
  2. Common use
    • Range out of bounds: The resource is 1000 bytes long and the client asks for bytes 1500 to 2000.
    • Nonexistent resources: No range can be fulfilled for a resource that does not exist.
  3. Response content: It must include Content-Range in the form bytes */[resource-size], indicating the total size.

Usage example

Request with an invalid range
GET /file.txt HTTP/1.1
Host: www.example.com
Range: bytes=1500-2000
Server response
HTTP/1.1 416 Range Not Satisfiable
Content-Range: bytes */1000
Content-Type: text/html

<html><body>
  <h1>Range not satisfiable</h1>
  <p>The requested range is not valid for the size of the resource.</p>
</body></html>

The response includes Content-Range with the size of the resource so the client can adjust its request.

Direct link to this code
417
Expectation Failed

The server cannot meet the requirements of the request's Expect header.

Explanation

  1. Purpose: To report that the expectation stated in Expect cannot be met.
  2. Common use
    • Expect header: Expect: 100-continue indicates that the client expects a 100 Continue before sending the body.
    • Unmet expectations: If the server cannot meet it, it responds 417.
  3. Response content: It can explain that the expectation cannot be met.

Usage example

Request with an Expect header
POST /api/resource HTTP/1.1
Host: www.example.com
Expect: 100-continue
Content-Type: application/json
Content-Length: 348

{
  "name": "John Smith",
  "email": "[email protected]"
}
Server response
HTTP/1.1 417 Expectation Failed
Content-Type: text/html

<html><body>
  <h1>Expectation failed</h1>
  <p>The server cannot meet the expectation specified in the Expect header.</p>
</body></html>

It tells the client to adjust its request because the expectation cannot be met.

Direct link to this code
418
I'm a Teapotnon-standard

A humorous reference to the Hyper Text Coffee Pot Control Protocol (HTCPCP), defined in RFC 2324 in 1998 as an April Fools' joke. It is not used in real applications, but it remains as a historical curiosity.

Explanation

  1. Purpose: To indicate that the server is a teapot and cannot brew coffee. It is a joke with no practical purpose.
  2. Common use
    • Humor: A nod to the RFC 2324 specification.
    • Learning examples: It is mentioned to illustrate how status codes work.
  3. Response content: It may include a humorous message.

Usage example

Client request (RFC 2324)
BREW /coffee HTTP/1.1
Host: www.example.com
Server response (as a teapot)
HTTP/1.1 418 I'm a Teapot
Content-Type: text/html

<html><body>
  <h1>I'm a teapot</h1>
  <p>I cannot brew coffee because I am a teapot.</p>
</body></html>

A historical curiosity from the world of web protocols.

Direct link to this code
420
Enhance Your Calmnon-standard

A non-standard code the Twitter API used to signal rate limiting: the client sent too many requests in a short time and must slow down. It was replaced by the standard 429 Too Many Requests.

Explanation

  1. Purpose: To report that the request limit was exceeded and that the frequency must be reduced to avoid being blocked.
  2. Common use
    • Rate limiting: To control load by limiting the number of requests per period.
    • Twitter API: Used by Twitter before it adopted 429.
  3. Response content
    • Error message: It may ask you to reduce the frequency.
    • Retry-After (optional): When to try again.

Usage example

Request that exceeds the limit
GET /api/tweets HTTP/1.1
Host: api.twitter.com
Server response (deprecated)
HTTP/1.1 420 Enhance Your Calm
Content-Type: application/json

{ "error": "You are being rate limited. Enhance your calm and try again later." }

It is not part of the official specification and was replaced by 429.

Direct link to this code
421
Misdirected Request

The request was sent to a server that cannot produce an appropriate response: it has no authority over the resource or is not configured to handle it.

Explanation

  1. Purpose: To report that the request reached the wrong server, one that is not authorized or not configured to handle it.
  2. Common use
    • Server configurations: Environments with multiple servers where one is not the right one for the request.
    • Incorrect routing: Load balancers or proxies that send the request to a server that cannot handle it.
  3. Response content
    • Error message: It can explain that the request was misdirected.
    • Possible solutions: Where to send the request or how to fix the problem.

Usage example

Request to the wrong server
GET /resource HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 421 Misdirected Request
Content-Type: text/html

<html><body>
  <h1>Misdirected request</h1>
  <p>The request was sent to a server that cannot produce an appropriate response.</p>
</body></html>

The request needs to be sent to a different server that can respond appropriately.

Direct link to this code
422
Unprocessable Entity

The server understands the content type and the syntax is correct, but it cannot process the instructions because of semantic errors. It originated in WebDAV but is used in many other contexts.

Explanation

  1. Purpose: To report that the request was received and understood, but cannot be processed because of semantic problems in the content.
  2. Common use
    • Validation errors: Missing required fields, out-of-range values or incorrect formats.
    • Semantic inconsistencies: Data that is internally inconsistent or makes no logical sense according to the server's rules.
  3. Response content
    • Error message: It describes the error and which parts of the request caused it.
    • Validation details: Specific details so the client can correct the errors.

Usage example

Request with invalid data
POST /users HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "name": "John",
  "email": "invalid email"
}
Server response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "errors": {
    "email": "The email format is not valid."
  }
}

The response usually describes the problem in detail so the client can correct the errors and resend the request.

Direct link to this code
423
Locked

Specific to WebDAV. The resource being accessed is locked and cannot be modified.

Explanation

  1. Purpose: To report that the resource is locked until the lock is released, avoiding conflicts in concurrent operations.
  2. Common use
    • WebDAV operations: A resource locked by a WebDAV operation to prevent concurrent modifications.
    • Concurrency control: To coordinate access and avoid inconsistent simultaneous changes.
  3. Response content: It can explain that the resource is locked and give details about the lock.

Usage example

Request to modify a locked resource
PROPPATCH /file HTTP/1.1
Host: www.example.com
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<propertyupdate xmlns="DAV:">
  <set><prop><author>John Smith</author></prop></set>
</propertyupdate>
Server response
HTTP/1.1 423 Locked
Content-Type: text/html

<html><body>
  <h1>Resource locked</h1>
  <p>The requested resource is locked and cannot be modified.</p>
</body></html>

It is used in WebDAV to manage concurrent access to resources and avoid conflicts.

Direct link to this code
424
Failed Dependency

Specific to WebDAV. The request failed because a previous request it depended on failed.

Explanation

  1. Purpose: To report that the request cannot be completed because it depends on another operation that failed.
  2. Common use
    • WebDAV operations: A request in a sequence depends on the successful completion of a previous one that failed.
    • Dependent transactions: The failure of one operation prevents the following ones from running.
  3. Response content: It can explain that the request failed because of a failed dependency.

Usage example

First request (LOCK), which fails
LOCK /file HTTP/1.1
Host: www.example.com
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<lockinfo xmlns="DAV:">
  <lockscope><exclusive/></lockscope>
  <locktype><write/></locktype>
  <owner><href>https://www.example.com/user</href></owner>
</lockinfo>

→ HTTP/1.1 403 Forbidden
Second request (PROPPATCH) and its response
PROPPATCH /file HTTP/1.1
Host: www.example.com
Content-Type: application/xml

…

HTTP/1.1 424 Failed Dependency
Content-Type: text/html

<html><body>
  <h1>Failed dependency</h1>
  <p>The request could not be completed because it depends on another request that failed.</p>
</body></html>

It handles interdependent operations that require the successful completion of previous requests.

Direct link to this code
425
Too Early

The server is unwilling to process a request that might be replayed. It is part of the strategy to avoid premature replays with TLS 1.3 and its 0-RTT (Zero Round Trip Time) extension.

Explanation

  1. Purpose: To report that processing the request now carries security risks, such as requests being replayed before a secure connection is fully established.
  2. Common use
    • TLS 0-RTT: It allows data to be sent before the connection is fully established; it improves latency but introduces the risk of replay attacks.
    • Security: The server avoids processing prematurely so as not to expose vulnerabilities.
  3. Response content: It can explain that the request is too early.

Usage example

Request that is too early
POST /api/resource HTTP/1.1
Host: www.example.com
Early-Data: 1

{ "data": "example" }
Server response
HTTP/1.1 425 Too Early
Content-Type: text/html

<html><body>
  <h1>Too early</h1>
  <p>The server is unwilling to process the request at this time. Please try again later.</p>
</body></html>

It prevents requests from being replayed prematurely when a secure connection has not yet been fully established.

Direct link to this code
426
Upgrade Required

The server refuses to process the request with the current protocol, but will do so if the client switches to another protocol.

Explanation

  1. Purpose: To report that the client must upgrade to a different protocol, needed when the server requires capabilities from a newer version.
  2. Common use
    • Protocol upgrade: Switching from HTTP/1.1 to HTTP/2 or to WebSocket.
    • Security improvement: Forcing a more secure or efficient protocol.
  3. Response content
    • Upgrade header: It specifies the protocol or protocols the client must switch to.
    • Error message: It can explain that the upgrade is required.

Usage example

Request with a protocol that is not accepted
GET /resource HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 426 Upgrade Required
Upgrade: HTTP/2.0
Content-Type: text/html

<html><body>
  <h1>Upgrade required</h1>
  <p>The server requires you to upgrade your protocol to HTTP/2.0 to process this request.</p>
</body></html>

It improves the compatibility, security or efficiency of communication between client and server.

Direct link to this code
428
Precondition Required

The server requires the request to be conditional: it must include headers such as If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since or If-Range. The goal is to avoid editing conflicts when several users modify the same resource.

Explanation

  1. Purpose
    • Avoiding conflicts: To ensure that modifications are made only if the resource has not changed since the client last saw it.
    • Data consistency: To guarantee that the client has a current copy before modifying it.
  2. Common use
    • Optimistic concurrency control: RESTful APIs where several clients modify the same resource.
    • Conditional validations: When it is crucial to process only if certain conditions are true.
  3. Response content: It can explain that a precondition is required and suggest the headers to use.

Usage example

Request without conditional headers
PUT /resource/123 HTTP/1.1
Host: www.example.com
Content-Type: application/json

{ "name": "Updated Resource" }
Server response
HTTP/1.1 428 Precondition Required
Content-Type: text/html

<html><body>
  <h1>Precondition Required</h1>
  <p>You must make this request with a precondition. Use the If-Match header to make sure the resource has not been modified.</p>
</body></html>

It requires conditional headers to avoid conflicts and ensure consistency when several clients modify the same resource.

Direct link to this code
429
Too Many Requests

The client sent too many requests in a given period of time and the server rejects the request to avoid overload. It implements rate limiting policies and protects resources against abuse.

Explanation

  1. Purpose
    • Rate limiting: To control the number of requests per period to avoid overload.
    • Protection against abuse: To prevent excessive use that affects performance and availability for other users.
  2. Common use
    • APIs: Limiting requests per minute, hour or day.
    • Web servers: To manage traffic and prevent denial-of-service (DoS) attacks.
  3. Response content
    • Error message: It explains that too many requests were sent and when to retry.
    • Retry-After (optional): How long to wait before trying again.

Usage example

Request that exceeds the limit
GET /api/resource HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 3600

{
  "error": "Too Many Requests",
  "message": "You have made too many requests in a short time. Please wait an hour before trying again."
}

It protects server resources and guarantees availability for all users; Retry-After indicates how long to wait.

Direct link to this code
431
Request Header Fields Too Large

The server refuses to process the request because one or more header fields are too large, either the total size or a single oversized header.

Explanation

  1. Purpose
    • Server protection: To avoid overload from headers that are too large.
    • Size control: To guarantee manageable headers, protecting against attacks or configuration errors.
  2. Common use
    • Excessive headers: Clients that send too much data in the headers, intentionally or by mistake.
    • Server limit: Maximum size configured for headers.
  3. Response content
    • Error message: It explains that one or more headers are too large.
    • Correction options: Suggestions to reduce the size.

Usage example

Request with headers that are too large
GET /resource HTTP/1.1
Host: www.example.com
X-Custom-Header: [a very long header…]
…
Server response
HTTP/1.1 431 Request Header Fields Too Large
Content-Type: text/html

<html><body>
  <h1>Request header fields too large</h1>
  <p>One or more header fields in the request are too large.</p>
</body></html>

It protects the server from excessive headers and keeps it able to serve other requests.

Direct link to this code
444
No Responsenon-standard

A non-standard code specific to Nginx. It indicates that the server closed the connection without sending a response. It is not defined in the HTTP standards and is not used outside Nginx.

Explanation

  1. Purpose
    • Closing the connection: Without sending headers or a body; useful to block malicious or unnecessary requests.
    • Mitigating attacks: For example DoS, where it is better to close the connection without responding.
  2. Common use
    • Nginx configuration: Blocking IPs, specific requests or suspicious behavior.
    • Efficiency: By not responding, the server saves resources.
  3. Response content: Nothing is sent to the client; the server simply closes the connection.

Usage example

Example in the Nginx configuration
server {
  listen 80;
  server_name www.example.com;

  location / {
    if ($http_user_agent ~* "malicious_bot") {
      return 444;
    }
    proxy_pass http://backend_server;
  }
}

If the user agent matches "malicious_bot", Nginx closes the connection without sending a response.

Direct link to this code
450
Blocked by Windows Parental Controlsnon-standard

A non-standard code defined by Microsoft: access to the resource was blocked by Windows parental controls. It is specific to certain Windows environments.

Explanation

  1. Purpose
    • Content blocking: To indicate that access was blocked by parental control restrictions.
    • Parental controls: To help administrators and parents restrict inappropriate content.
  2. Common use
    • Windows Parental Controls: Systems with parental controls enabled that block certain sites or content.
    • Network administration: Family or educational environments.
  3. Response content: It may include a message explaining the block, depending on the implementation.

Usage example

Request for a blocked resource
GET /blocked-site HTTP/1.1
Host: www.example.com
Response indicating the block
HTTP/1.1 450 Blocked by Windows Parental Controls
Content-Type: text/html

<html><body>
  <h1>Access blocked</h1>
  <p>Access to this resource was blocked by Windows parental controls.</p>
</body></html>

It restricts access to unwanted content on Windows-managed devices; it is not part of the HTTP specification.

Direct link to this code
451
Unavailable For Legal Reasons

The resource is not available because of legal restrictions: the server received a legal order forbidding it from providing access to the resource.

Explanation

  1. Purpose
    • Legal compliance: To report that the resource cannot be provided because of a court order or a government request.
    • Transparency: To give a clear and specific reason instead of a generic 403 Forbidden.
  2. Common use
    • Censorship: A government or another legal entity ordered a site or resource to be blocked.
    • Copyright: Content removed because of intellectual property violations.
  3. Response content
    • Error message: It explains the legal reason for the unavailability.
    • Link header: It can point, with rel="blocked-by", to the entity that imposed the restriction.

Usage example

Request for a resource blocked for legal reasons
GET /censored-article HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 451 Unavailable For Legal Reasons
Link: <https://www.ejemplo.com/orden-legal>; rel="blocked-by"
Content-Type: text/html

<html><body>
  <h1>Unavailable for legal reasons</h1>
  <p>This content is not available in your region because of a legal order.</p>
</body></html>

The number 451 is a tribute to Ray Bradbury's novel Fahrenheit 451. It makes it possible to distinguish a legal restriction from a simple permissions problem.

Direct link to this code
499
Client Closed Requestnon-standard

A non-standard Nginx code. The client closed the connection before the server could send a response.

Explanation

  1. Purpose: To record in the server logs that the request was interrupted on the client side, not because of a server failure.
  2. Common use
    • Client timeouts: The client had a shorter timeout than the backend processing time.
    • Interrupted browsing: The user closed the tab or cancelled the load before receiving the response.
  3. Response content: No response is sent: the connection no longer exists. It only appears in the access logs.

Usage example

Typical line in the Nginx log
192.0.2.10 - - [01/Oct/2026:10:15:32 -0300] "POST /api/report HTTP/1.1" 499 0 "-" "Mozilla/5.0"

If you see a lot of 499s in the logs, it usually means the backend takes longer than the client is willing to wait.

Direct link to this code

Family 5xx Server errors

The server failed to process an apparently valid request.

500
Internal Server Error

The server encountered an unexpected condition that prevented it from completing the request. It is the generic server error: it is used when there is no more specific 5xx code.

Explanation

  1. Purpose: To report that the problem is on the server side, not in the client's request.
  2. Common use
    • Unhandled exceptions: An error in the application code that was not caught.
    • Dependency failures: The database or an internal service did not respond as expected.
    • Incorrect configuration: Misconfigured file permissions, environment variables or modules.
  3. Response content
    • Generic message: In production it must not expose internal details (stack traces, paths, queries).
    • Error identifier: Good practice: include an ID to trace the problem in the logs.

Usage example

Client request
GET /api/orders/42 HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again later.",
  "error_id": "a1b2c3d4"
}

For QA, a 500 is almost always a reproducible backend bug: report it with the exact request and the error ID if there is one.

Direct link to this code
501
Not Implemented

The server does not support the functionality needed to fulfill the request. It usually means it does not recognize the HTTP method or that the functionality has not been implemented yet.

Explanation

  1. Purpose: To report that the server cannot process that type of request, now or for any resource (unlike 405, which is per resource).
  2. Common use
    • Unknown methods: A method the server does not recognize at all.
    • Functionality in development: An endpoint that is planned but not implemented yet.
  3. Response content: It may include a message indicating what is not implemented.

Usage example

Request with an unsupported method
PROPFIND /documents/ HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 501 Not Implemented
Content-Type: text/html

<html><body>
  <h1>Not implemented</h1>
  <p>The server does not support the PROPFIND method.</p>
</body></html>

Key difference from 405: with 501 the server does not support the method for any resource; with 405 it knows the method but does not allow it for that resource.

Direct link to this code
502
Bad Gateway

The server, acting as a gateway or proxy, received an invalid response from the origin server it forwarded the request to.

Explanation

  1. Purpose: To report that the intermediary (reverse proxy, load balancer, CDN) could not get a valid response from the backend.
  2. Common use
    • Backend down: The application server is not running or is refusing connections.
    • Malformed response: The backend returned something the proxy cannot interpret.
    • Deployments: During a deploy, the proxy tries to talk to an instance that has not started yet.
  3. Response content: It is usually a generic proxy page (Nginx, Apache, Cloudflare) with the message Bad Gateway.

Usage example

Client request
GET /api/products HTTP/1.1
Host: www.example.com
Proxy response
HTTP/1.1 502 Bad Gateway
Server: nginx
Content-Type: text/html

<html><body>
  <h1>502 Bad Gateway</h1>
  <p>The origin server returned an invalid response.</p>
</body></html>

The problem is between the proxy and the backend, not in the client's request. Check whether the application service is up.

Direct link to this code
503
Service Unavailable

The server is temporarily unavailable, usually because of maintenance or overload. The condition is temporary and is expected to be resolved.

Explanation

  1. Purpose: To report that the service exists but cannot handle the request right now.
  2. Common use
    • Scheduled maintenance: The site is deliberately out of service.
    • Overload: The server has no capacity to handle more requests.
    • Dependencies down: A critical service (database, cache) is not responding.
  3. Response content
    • Retry-After: It indicates, in seconds or with a date, when to try again.
    • Message: A maintenance page or a JSON with the service status.

Usage example

Client request
GET / HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 503 Service Unavailable
Retry-After: 1800
Content-Type: text/html

<html><body>
  <h1>Service unavailable</h1>
  <p>We are doing maintenance. Please try again in 30 minutes.</p>
</body></html>

For SEO it is best to use 503 with Retry-After during maintenance: search engines understand it is temporary and do not de-index the page.

Direct link to this code
504
Gateway Timeout

The server, acting as a gateway or proxy, did not receive a response from the origin server in time.

Explanation

  1. Purpose: To report that the intermediary waited for a response from the backend and the time limit ran out.
  2. Common use
    • Slow queries: An endpoint that takes longer than the timeout configured in the proxy.
    • Overloaded backend: The application server is alive but cannot keep up.
    • Network problems: Latency or packet loss between the proxy and the origin.
  3. Response content: A generic proxy page indicating Gateway Timeout.

Usage example

Client request
GET /api/annual-report HTTP/1.1
Host: www.example.com
Proxy response
HTTP/1.1 504 Gateway Timeout
Server: nginx
Content-Type: text/html

<html><body>
  <h1>504 Gateway Timeout</h1>
  <p>The origin server did not respond in time.</p>
</body></html>

Difference from 502: with 502 the backend returned something invalid; with 504 it simply did not respond in time. It usually points to a performance problem.

Direct link to this code
505
HTTP Version Not Supported

The server does not support, or refuses to support, the HTTP version used in the request.

Explanation

  1. Purpose: To report that the protocol version indicated in the request line is not compatible with the server.
  2. Common use
    • Old clients: Tools that use HTTP/1.0 against servers that require HTTP/1.1 or later.
    • Invalid versions: A malformed or nonexistent version in the request.
  3. Response content: It can indicate which versions are supported.

Usage example

Request with an unsupported version
GET /resource HTTP/3.5
Host: www.example.com
Server response
HTTP/1.1 505 HTTP Version Not Supported
Content-Type: text/html

<html><body>
  <h1>HTTP version not supported</h1>
  <p>This server supports HTTP/1.1 and HTTP/2.</p>
</body></html>

Rare in practice; it shows up mostly with misconfigured clients or scripts.

Direct link to this code
506
Variant Also Negotiates

A server configuration error: transparent content negotiation (RFC 2295) chose a variant that itself also negotiates, which creates a circular reference.

Explanation

  1. Purpose: To signal an internal error in the content negotiation configuration.
  2. Common use: Practically nonexistent outside servers that implement transparent negotiation; it indicates a loop in the variant configuration.
  3. Response content: An error message indicating the configuration problem.

Usage example

Client request
GET /document HTTP/1.1
Host: www.example.com
Accept: text/html, application/pdf
Server response
HTTP/1.1 506 Variant Also Negotiates
Content-Type: text/plain

Configuration error: the selected variant also negotiates content.

It is a server-side error that must be fixed in the content negotiation configuration.

Direct link to this code
507
Insufficient Storage

Specific to WebDAV. The server cannot store the representation needed to complete the request because it does not have enough space.

Explanation

  1. Purpose: To report that the operation requires more storage than the server has available.
  2. Common use
    • File uploads: A PUT or COPY on a WebDAV server with a full disk.
    • User quotas: The user exceeded their assigned storage quota.
  3. Response content: It can detail the available space or the quota exceeded.

Usage example

Request to upload a file
PUT /files/video.mp4 HTTP/1.1
Host: www.example.com
Content-Length: 4294967296
Server response
HTTP/1.1 507 Insufficient Storage
Content-Type: text/html

<html><body>
  <h1>Insufficient storage</h1>
  <p>There is not enough space to save the file.</p>
</body></html>

The condition is temporary if space is freed; the client can retry later.

Direct link to this code
508
Loop Detected

Specific to WebDAV. The server detected an infinite loop while processing a request with Depth: infinity, typically because of circular links or bindings.

Explanation

  1. Purpose: To report that the whole operation failed because traversing the resources would enter an endless cycle.
  2. Common use
    • Collections with circular references: A folder that contains a link to itself or to an ancestor.
    • Recursive operations: PROPFIND, COPY or MOVE with infinite depth.
  3. Response content: A message indicating that a loop was detected.

Usage example

Recursive request
PROPFIND /folder/ HTTP/1.1
Host: www.example.com
Depth: infinity
Server response
HTTP/1.1 508 Loop Detected
Content-Type: text/plain

A loop was detected while traversing /folder/link-to-folder/

Related to 208 Already Reported, which is the way to avoid this problem inside a 207 response.

Direct link to this code
510
Not Extended

The request needs additional protocol extensions that the server does not support or that were not declared (RFC 2774, HTTP Extension Framework).

Explanation

  1. Purpose: To report that the server's policy requires additional extensions to be declared to handle the request.
  2. Common use: Very rare in practice; the RFC 2774 extension framework is hardly ever implemented.
  3. Response content: It should describe which extensions are needed.

Usage example

Client request
GET /resource HTTP/1.1
Host: www.example.com
Server response
HTTP/1.1 510 Not Extended
Content-Type: text/plain

This request requires extension X to be processed.

A historical code; if you find it in production, check the server's specific documentation.

Direct link to this code
511
Network Authentication Required

The client needs to authenticate to gain network access. It is generated by network intermediaries (for example, Wi-Fi captive portals), not by the origin server.

Explanation

  1. Purpose: To indicate that the network requires authentication before allowing traffic, instead of silently redirecting to a login page.
  2. Common use
    • Captive portals: Wi-Fi in hotels, airports or cafés that requires accepting terms or signing in.
    • Corporate networks: Internet access conditional on authentication.
  3. Response content: A page with the authentication form or a link to the portal.

Usage example

Client request
GET https://www.example.com/ HTTP/1.1
Host: www.example.com
Network intermediary response
HTTP/1.1 511 Network Authentication Required
Content-Type: text/html

<html><body>
  <h1>Network authentication required</h1>
  <p>Iniciá sesión en el <a href="https://portal.wifi-example.com/login">portal de acceso</a> para navegar.</p>
</body></html>

It lets applications detect a captive portal instead of interpreting the login page as the site's real response.

Direct link to this code
520
Web Server Returned an Unknown Errornon-standard

A non-standard Cloudflare code. The origin server returned an empty, unknown or unexpected response that Cloudflare could not interpret.

Explanation

  1. Purpose: To group origin failures that do not fit any other code: connection reset, invalid headers, empty response.
  2. Common use
    • Headers too large: The origin sends headers that exceed Cloudflare's limits.
    • Connection reset: The origin cuts the connection after receiving the request.
    • Empty response: The origin does not return any HTTP header.

Usage example

Cloudflare response
HTTP/1.1 520
Server: cloudflare
Content-Type: text/html

<html><body>
  <h1>Error 520</h1>
  <p>Web server is returning an unknown error.</p>
</body></html>

To diagnose it you need to check the origin server's logs; the problem is not in Cloudflare or in the client.

Direct link to this code
521
Web Server Is Downnon-standard

A non-standard Cloudflare code. The origin server refused Cloudflare's connection.

Explanation

  1. Purpose: To indicate that Cloudflare could resolve the origin but it does not accept connections.
  2. Common use
    • Server shut down: The origin's web service is not running.
    • Firewall: The origin blocks Cloudflare's IPs.

Usage example

Cloudflare response
HTTP/1.1 521
Server: cloudflare

Web server is down

Check that the origin web server is up and accepts connections from Cloudflare's IP ranges.

Direct link to this code
522
Connection Timed Outnon-standard

A non-standard Cloudflare code. The TCP connection with the origin server could not be established within the time limit.

Explanation

  1. Purpose: To indicate that the TCP handshake with the origin was not completed in time.
  2. Common use
    • Overloaded origin: It cannot accept new connections.
    • Firewall or rate limiting: It drops Cloudflare's packets.
    • Wrong IP: The DNS record points to the wrong IP.

Usage example

Cloudflare response
HTTP/1.1 522
Server: cloudflare

Connection timed out

Difference from 524: with 522 the connection was never established; with 524 it was established but the origin did not respond.

Direct link to this code
523
Origin Is Unreachablenon-standard

A non-standard Cloudflare code. Cloudflare cannot reach the origin server, usually because of DNS or incorrect network routes.

Explanation

  1. Purpose: To indicate that the origin's IP cannot be reached from Cloudflare's network.
  2. Common use
    • Misconfigured DNS: The record points to a nonexistent or internal IP.
    • Routing problems: The origin's provider has network problems.

Usage example

Cloudflare response
HTTP/1.1 523
Server: cloudflare

Origin is unreachable

Check the domain's DNS records in Cloudflare and the origin server's connectivity.

Direct link to this code
524
A Timeout Occurrednon-standard

A non-standard Cloudflare code. The TCP connection with the origin was established correctly, but the origin did not return an HTTP response within the time limit (100 seconds by default).

Explanation

  1. Purpose: To indicate that the origin accepted the connection but took too long to respond.
  2. Common use
    • Long-running processes: Heavy reports, exports or queries that exceed 100 seconds.
    • Slow backend: Performance problems in the application or the database.

Usage example

Cloudflare response
HTTP/1.1 524
Server: cloudflare

A timeout occurred

It is conceptually equivalent to a 504. The solution is usually to optimize the endpoint or move it to asynchronous processing (202 Accepted).

Direct link to this code
525
SSL Handshake Failednon-standard

A non-standard Cloudflare code. The SSL/TLS handshake between Cloudflare and the origin server failed.

Explanation

  1. Purpose: To indicate that an encrypted connection with the origin could not be negotiated.
  2. Common use
    • Full SSL mode without a certificate: Cloudflare expects HTTPS on the origin but the origin does not support it on port 443.
    • Incompatible ciphers: The origin does not support the cipher suites Cloudflare offers.

Usage example

Cloudflare response
HTTP/1.1 525
Server: cloudflare

SSL handshake failed

Check that the origin has a valid certificate installed and that Cloudflare's SSL mode matches the server configuration.

Direct link to this code
526
Invalid SSL Certificatenon-standard

A non-standard Cloudflare code. Cloudflare could not validate the origin server's SSL certificate (Full Strict mode).

Explanation

  1. Purpose: To indicate that the origin's certificate is expired, self-signed or does not match the domain.
  2. Common use
    • Expired certificate: It needs to be renewed.
    • Self-signed certificate: With Full Strict, a certificate issued by a trusted CA or a Cloudflare Origin Certificate is required.

Usage example

Cloudflare response
HTTP/1.1 526
Server: cloudflare

Invalid SSL certificate

Install a valid certificate on the origin or use a Cloudflare Origin Certificate.

Direct link to this code

The most confusing ones

Differences every tester should know

401 vs 403

Unauthorized vs Forbidden

401: credentials are missing or invalid; authenticating may fix it. 403: the server knows who you are and still won't let you in; authenticating changes nothing.

301 vs 308

Permanent redirect

Both are permanent, but 308 guarantees that the method and body are preserved. With 301, a POST may end up as a GET.

302 vs 307

Temporary redirect

Same logic: 307 keeps the original method; 302 lets the client change it to GET.

404 vs 410

Not found vs removed

404 promises nothing about the resource's future. 410 states that it is gone for good and that search engines should stop requesting it.

400 vs 422

Syntax vs semantics

400: the request is malformed. 422: the syntax is correct but the data fails business validations.

502 vs 504

Gateway

502: the origin server returned something invalid. 504: it simply did not respond in time.