The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

HTTP::Promise::Status - HTTP Status Codes & Locale Equivalents

SYNOPSIS

use HTTP::Promise::Status ':common';
use HTTP::Promise::Status ':all';
say HTTP::Promise::Status::HTTP_TOO_MANY_REQUESTS;
# returns code 429

say $HTTP::Promise::Status::CODES_LOCALE->{fr_FR}->{429} # Trop de requête
# In Japanese: リクエスト過大で拒否した
say $HTTP::Promise::Status::CODES_LOCALE->{ja_JP}->{429}

But maybe more simply:

my $status = HTTP::Promise::Status->new;
say $status->status_message( 429 => 'ja_JP' );
# Or without the language code parameter, it will default to en_GB
say $status->status_message( 429 );

# Is success
say $status->is_info( 102 ); # true
say $status->is_success( 200 ); # true
say $status->is_redirect( 302 ); # true
say $status->is_error( 404 ); # true
say $status->is_client_error( 403 ); # true
say $status->is_server_error( 501 ); # true

VERSION

v0.1.0

DESCRIPTION

This module allows the access of http constants similar to mod_perl and using their numeric value, and also allows to get the localised version of the http status for a given code for currently supported languages: fr_FR (French), en_GB (British English) and ja_JP (Japanese), de_DE (German), ko_KR (Korean), ru_RU (Russian), zh_TW (Taiwanese).

It also provides some functions to check if a given code is an information, success, redirect, error, client error or server error code.

METHODS

init

Creates an instance of HTTP::Promise::Status and returns the object.

convert_short_lang_to_long

Given a 2 characters language code (not case sensitive) and this will return its iso 639 5 characters equivalent for supported languages.

For example:

HTTP::Promise::Status->convert_short_lang_to_long( 'zh' );
# returns: zh_TW

is_cacheable_by_default

Return true if the 3-digits code provided indicates that a response is cacheable by default, and it can be reused by a cache with heuristic expiration. All other status codes are not cacheable by default. See RFC 7231 - HTTP/1.1 Semantics and Content, Section 6.1. Overview of Status Codes.

is_client_error

Returns true if the 3-digits code provided is between 400 and 500

is_error

Returns true if the 3-digits code provided is between 400 and 600

is_info

Returns true if the 3-digits code provided is between 100 and 200

is_redirect

Returns true if the 3-digits code provided is between 300 and 400

is_server_error

Returns true if the 3-digits code provided is between 500 and 600

is_success

Returns true if the 3-digits code provided is between 200 and 300

status_message

Provided with a 3-digits http code and an optional language code such as en_GB and this will return the status message in its localised form.

This is useful to provide response to error in the user preferred language. You can also use it to set a json response with the http error code along with a localised status message.

If no language code is provided, this will default to en_GB.

See "supported_languages" for the supported languages.

supported_languages

This will return a sorted array reference of support languages for status codes.

The following language codes are currently supported: de_DE (German), en_GB (British English), fr_FR (French), ja_JP (Japanese), ko_KR (Korean), ru_RU (Russian) and zh_TW (Traditional Chinese as spoken in Taiwan).

Feel free to contribute those codes in other languages.

CONSTANTS

The following constants can be exported. You can use the :all tag to export them all, such as:

use HTTP::Promise::Status qw( :all );

or you can use the tag :common to export the following common status codes:

HTTP_NETWORK_AUTHENTICATION_REQUIRED
HTTP_FORBIDDEN
HTTP_NOT_FOUND
HTTP_OK
HTTP_TEMPORARY_REDIRECT
HTTP_INTERNAL_SERVER_ERROR

HTTP_CONTINUE (100)

See rfc 7231, section 5.1.1 and section 6.2.1 and Mozilla docs

This is provisional response returned by the web server upon an abbreviated request to find out whether the web server will accept the actual request. For example when the client is sending a large file in chunks, such as in PUT request (here a 742MB file):

PUT /some//big/file.mp4 HTTP/1.1
Host: www.example.org
Content-Type: video/mp4
Content-Length: 778043392
Expect: 100-continue

If the server refused, it could return a 413 Request Entity Too Large or 405 Method Not Allowed or even 401 Unauthorized, or even a 417 Expectation Failed if it does not support this feature.

A response 417 Expectation Failed means the server is likely a HTTP/1.0 server or does not understand the request and the actual request must be sent, i.e. without the header field Expect: 100-continue

In some REST API implementation, the server response code 417 is used to mean the server understood the requested, but rejected it. This is a divergent use of the original purpose of this code.

HTTP_SWITCHING_PROTOCOLS (101)

See rfc7231, section 6.2.2

This is used to indicate that the TCP conncection is switching to a different protocol.

This is typically used for the WebSocket protocol, which uses initially a HTTP handshake when establishing the connection. For example:

GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Origin: http://example.com
Sec-WebSocket-Protocol: chat, superchat
Sec-WebSocket-Version: 13

Then the server could reply something like:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: chat

HTTP_PROCESSING (102)

See rfc 2518 on WebDAV

This is returned to notify the client that the server is currently processing the request and that it is taking some time.

The server could return repeated instance of this response code until it is done processing the request and then send back the actual final response headers.

HTTP_EARLY_HINTS (103)

See rfc 8297 on Indicating Hints

This is a preemptive return code to notify the client to make some optimisations, while the actual final response headers are sent later. For example:

HTTP/1.1 103 Early Hints
Link: </style.css>; rel=preload; as=style
Link: </script.js>; rel=preload; as=script

then, a few seconds, or minutes later:

HTTP/1.1 200 OK
Date: Mon, 16 Apr 2022 02:15:12 GMT
Content-Length: 1234
Content-Type: text/html; charset=utf-8
Link: </style.css>; rel=preload; as=style
Link: </script.js>; rel=preload; as=script

HTTP_OK (200)

See rfc7231, section 6.3.1

This is returned to inform the request has succeeded. It can also alternatively be 204 No Content when there is no response body.

For example:

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 184
Connection: keep-alive
Cache-Control: s-maxage=300, public, max-age=0
Content-Language: en-US
Date: Mon, 18 Apr 2022 17:37:18 GMT
ETag: "2e77ad1dc6ab0b53a2996dfd4653c1c3"
Server: Apache/2.4
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Vary: Accept-Encoding,Cookie
Age: 7

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>A simple webpage</title>
</head>
<body>
  <h1>Simple HTML5 webpage</h1>
  <p>Hello, world!</p>
</body>
</html>

HTTP_CREATED (201)

See rfc7231, section 6.3.2

This is returned to notify the related resource has been created, most likely by a PUT request, such as:

PUT /some/where HTTP/1.1
Content-Type: text/html
Host: example.org

Then, the server would reply:

HTTP/1.1 201 Created
ETag: "foo-bar"

HTTP_ACCEPTED (202)

See rfc7231, section 6.3.3

This is returned when the web server has accepted the request, without guarantee of successful completion.

Thus, the remote service would typically send an email to inform the user of the status, or maybe provide a link in the header. For example:

POST /some/where HTTP/1.1
Content-Type: application/json

Then the server response:

HTTP/1.1 202 Accepted
Link: </some/status/1234> rel="https://example.org/status"
Content-Length: 0

HTTP_NON_AUTHORITATIVE (203)

See rfc 7231, section 6.3.4

This would typically be returned by an HTTP proxy after it has made some change to the content.

HTTP_NO_CONTENT (204)

See rfc 7231, section 6.3.5

This is returned when the request was processed successfully, but there is no body content returned.

HTTP_RESET_CONTENT (205)

See rfc 7231, section 6.3.6

This is to inform the client the request was successfully processed and the content should be reset, like a web form.

HTTP_PARTIAL_CONTENT (206)

See rfc 7233 on Range Requests

This is returned in response to a request for partial content, such as a certain number of bytes from a video. For example:

GET /video.mp4 HTTP/1.1
Range: bytes=1048576-2097152

Then, the server would reply something like:

HTTP/1.1 206 Partial Content
Content-Range: bytes 1048576-2097152/3145728
Content-Type: video/mp4

HTTP_MULTI_STATUS (207)

See rfc 4918 on WebDAV

This is returned predominantly under the WebDav protocol, when multiple operations occurred. For example:

HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset="utf-8"
Content-Length: 637

<d:multistatus xmlns:d="DAV:">
    <d:response>
        <d:href>/calendars/johndoe/home/132456762153245.ics</d:href>
        <d:propstat>
            <d:prop>
                <d:getetag>"xxxx-xxx"</d:getetag>
            </d:prop>
            <d:status>HTTP/1.1 200 OK</d:status>
        </d:propstat>
    </d:response>
    <d:response>
        <d:href>/calendars/johndoe/home/fancy-caldav-client-1234253678.ics</d:href>
        <d:propstat>
            <d:prop>
                <d:getetag>"5-12"</d:getetag>
            </d:prop>
            <d:status>HTTP/1.1 200 OK</d:status>
        </d:propstat>
    </d:response>
</d:multistatus>

HTTP_ALREADY_REPORTED (208)

See rfc 5842, section 7.1 on WebDAV bindings

This is returned predominantly under the WebDav protocol.

HTTP_IM_USED (226)

See rfc 3229 on Delta encoding

IM stands for Instance Manipulation.

This is an HTTP protocol extension used to indicate a diff performed and return only a fraction of the resource. This is especially true when the actual resource is large and it would be a waste of bandwidth to return the entire resource. For example:

GET /foo.html HTTP/1.1
Host: bar.example.net
If-None-Match: "123xyz"
A-IM: vcdiff, diffe, gzip

Then, the server would reply something like:

HTTP/1.1 226 IM Used
ETag: "489uhw"
IM: vcdiff
Date: Tue, 25 Nov 1997 18:30:05 GMT
Cache-Control: no-store, im, max-age=30

See also the HTTP range request triggering a 206 Partial Content response.

HTTP_MULTIPLE_CHOICES (300)

See rfc 7231, section 6.4.1 and rfc 5988 for the Link header.

See Mozilla documentation

This is returned when there is a redirection with multiple choices possible. For example:

HTTP/1.1 300 Multiple Choices
Server: Apache/2.4
Access-Control-Allow-Headers: Content-Type,User-Agent
Access-Control-Allow-Origin: *
Link: </foo> rel="alternate"
Link: </bar> rel="alternate"
Content-Type: text/html
Location: /foo

However, because there is no standard way to have the user choose, this response code is never used.

HTTP_MOVED_PERMANENTLY (301)

See rfc 7231, section 6.4.2

This is returned to indicate the target resource can now be found at a different location and all pointers should be updated accordingly. For example:

HTTP/1.1 301 Moved Permanently
Server: Apache/2.4
Content-Type: text/html; charset=utf-8
Date: Mon, 18 Apr 2022 17:33:08 GMT
Location: https://example.org/some/where/else.html
Keep-Alive: timeout=15, max=98
Accept-Ranges: bytes
Via: Moz-Cache-zlb05
Connection: Keep-Alive
Content-Length: 212

<!DOCTYPE html>
<html><head>
<title>301 Moved Permanently</title>
</head><body>
<h1>Moved Permanently</h1>
<p>The document has moved <a href="https://example.org/some/where/else.html">here</a>.</p>
</body></html>

See also 308 Permanent Redirect

HTTP_MOVED_TEMPORARILY (302)

See rfc 7231, section 6.4.3

This is returned to indicate the resource was found, but somewhere else. This is to be understood as a temporary change.

The de facto standard, divergent from the original intent, is to point the client to a new location after a POST request was performed. This is why the status code 307 was created.

See also 307 Temporary Redirect, which more formally tells the client to reformulate their request to the new location.

See also 303 See Other for a formal implementation of aforementioned de facto standard, i.e. GET new location after POST request.

HTTP_SEE_OTHER (303)

See rfc 7231, section 6.4.4

This is returned to indicate the result of processing the request can be found at another location. For example, after a POST request, such as:

HTTP/1.1 303 See Other
Server: Apache/2.4
Location: /worked/well

It is considered better to redirect once request has been processed rather than returning the result immediately in the response body, because in the former case, this wil register a new entry in the client history whereas with the former, this would force the user to re-submit if the user did a back in history.

HTTP_NOT_MODIFIED (304)

See rfc 7232, section 4.1 on Conditional Request

This is returned in response to a conditional GET or POST request with headers such as:

If-Match
If-None-Match
If-Modified-Since
If-Unmodified-Since
If-Range

For example:

GET /foo HTTP/1.1
Accept: text/html

Then, the server would reply something like:

HTTP/1.1 200 Ok
Content-Type: text/html
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Later, the client would do another request, such as:

GET /foo HTTP/1.1
Accept: text/html
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

And if nothing changed, the server would return something like this:

HTTP/1.1 304 Not Modified
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

HTTP_USE_PROXY (305)

See rfc 7231, section 6.4.5 and the rfc 2616, section 10.3.6 deprecating this status code

This is returned to indicate to the client to submit the request again, using a proxy. For example:

HTTP/1.1 305 Use Proxy
Location: https://proxy.example.org:8080/

This is deprecated and is not in use.

306 Switch Proxy

This is deprecated and now a reserved status code that was originally designed to indicate to the client the need to change proxy, but was deemed ultimately a security risk. See the original rfc draft

For example:

HTTP/1.1 306 Switch Proxy
Set-Proxy: SET; proxyURI="https://proxy.example.org:8080/" scope="http://", seconds=100

HTTP_TEMPORARY_REDIRECT (307)

See rfc 2731, section 6.4.7

This is returned to indicate the client to perform the request again at a different location. The difference with status code 302 is that the client would redirect to the new location using a GET method, whereas with the status code 307, they have to perform the same request.

For example:

HTTP/1.1 307 Temporary Redirect
Server: Apache/2.4
Location: https://example.org/some/where/else.html

HTTP_PERMANENT_REDIRECT (308)

See rfc 7538 on Permanent Redirect

Similar to the status code 307 and 302, the status code 308 indicates to the client to perform the request again at a different location and that the location has changed permanently. This echoes the status code 301, except that the standard with 301 is for clients to redirect using GET method even if originally the method used was POST. With the status code 308, the client must reproduce the request with the original method.

For example:

GET / HTTP/1.1
Host: example.org

Then, the server would respond something like:

HTTP/1.1 308 Permanent Redirect
Server: Apache/2.4
Content-Type: text/html; charset=UTF-8
Location: https://example.org/some/where/else.html
Content-Length: 393

<!DOCTYPE HTML>
<html>
   <head>
      <title>Permanent Redirect</title>
      <meta http-equiv="refresh"
            content="0; url=https://example.org/some/where/else.html">
   </head>
   <body>
      <p>
         The document has been moved to
         <a href="https://example.org/some/where/else.html"
         >https://example.org/some/where/else.html</a>.
      </p>
   </body>
</html>

HTTP_BAD_REQUEST (400)

See rfc 7231, section 6.5.1

This is returned to indicate the client made a request the server could not interpret.

This is generally used as a fallback client-error code when other mode detailed 4xx code are not suitable.

HTTP_UNAUTHORIZED (401)

See rfc 7235, section 3.1 on Authentication

See also Mozilla documentation

This is returned to indicate to the client it must authenticate first before issuing the request.

See also status code 403 Forbidden when client is outright forbidden from accessing the resource.

For example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic; realm="Secured area"

or, for APIs:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

or, combining both:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic; realm="Dev zone", Bearer

which equates to:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic; realm="Dev zone"
WWW-Authenticate: Bearer

So, for example, a user aladdin with password opensesame would result in the following request:

GET / HTTP/1.1
Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l

See also Mozilla documentation on Authorization header

HTTP_PAYMENT_REQUIRED (402)

See rfc 7231, section 6.5.2

This was originally designed to inform the client that the resource could only be accessed once payment was made, but is now reserved and its current use is left at the discretion of the site implementing it.

HTTP_FORBIDDEN (403)

See rfc 7231, section 6.5.3

See also Mozilla documentation

This is returned to indicate the client is barred from accessing the resource.

This is different from 405 Method Not Allowed, which is used when the client has proper permission to access the resource, but is using a method not allowed, such as using PUT instead of GET method.

HTTP_NOT_FOUND (404)

See rfc 7231, section 6.5.4

See also Mozilla documentation

This is returned to indicate the resource does not exist anymore.

HTTP_METHOD_NOT_ALLOWED (405)

See rfc 7231, section 6.5.5

This is returned to indicate the client it used a method not allowed, such as using PUT instead of GET. The server can point out the supported methods with the Allow header, such as:

HTTP/1.1 405 Method Not Allowed
Content-Type: text/html
Content-Length: 32
Allow: GET, HEAD, OPTIONS, PUT

<h1>405 Try another method!</h1>

HTTP_NOT_ACCEPTABLE (406)

See rfc 7231, section 6.5.6

This is returned to the client to indicate its requirements are not supported and thus not acceptable. This is in response to Accept, Accept-Charset, Accept-Encoding, Accept-Language headers

For example:

GET /foo HTTP/1.1
Accept: application/json
Accept-Language: fr-FR,en-GB;q=0.8,fr;q=0.6,en;q=0.4,ja;q=0.2

HTTP/1.1 406 Not Acceptable
Server: Apache/2.4
Content-Type: text/html

<h1>Je ne gère pas le type application/json</h1>

Then, the server would response something like:

HTTP_PROXY_AUTHENTICATION_REQUIRED (407)

See rfc 7235, section 3.2 on Authentication

This is returned to indicate the proxy used requires authentication. This is similar to the status code 401 Unauthorized.

HTTP_REQUEST_TIME_OUT (408)

See rfc 7231, section 6.5.7

This is returned to indicate the request took too long to be received and timed out. For example:

HTTP/1.1 408 Request Timeout
Connection: close
Content-Type: text/plain
Content-Length: 19

Too slow! Try again

HTTP_CONFLICT (409)

See rfc 7231, section 6.5.8

This is returned to indicate a request conflict with the current state of the target resource, such as uploading with PUT a file older than the remote one.

HTTP_GONE (410)

See rfc 7231, section 6.5.9

This is returned to indicate that the target resource is gone permanently. The subtle difference with the status code 404 is that with 404, the resource may be only temporally unavailable whereas with 410, this is irremediable. For example:

HTTP/1.1 410 Gone
Server: Apache/2.4
Content-Type: text/plain
Content-Length: 30

The resource has been removed.

HTTP_LENGTH_REQUIRED (411)

See rfc 7231, section 6.5.10

This is returned when the Content-Length header was not provided by the client and the server requires it to be present. Most servers can do without.

HTTP_PRECONDITION_FAILED (412)

See rfc 7232 on Conditional Request

This is returned when some preconditions set by the client could not be met.

For example:

Issuing a PUT request for a document if it does not already exist.

PUT /foo/new-article.md HTTP/1.1
Content-Type: text/markdown
If-None-Match: *

Update a document if it has not changed since last time (etag)

PUT /foo/old-article.md HTTP/1.1
If-Match: "1345-12315"
Content-Type: text/markdown

If those failed, it would return something like:

HTTP/1.1 412 Precondition Failed
Content-Type: text/plain
Content-Length: 64

The article you are tring to update has changed since last time.

If one adds the Prefer header, the servers will return the current state of the resource, thus saving a round of request with a GET, such as:

PUT /foo/old-article.md HTTP/1.1
If-Match: "1345-12315"
Content-Type: text/markdown
Prefer: return=representation

### Article version 2.1

Then, the server would respond something like:

HTTP/1.1 412 Precondition Failed
Content-Type: text/markdown
Etag: "4444-12345"
Vary: Prefer

### Article version 3.0

See also rfc 7240 about the Prefer header field and rfc 8144, Section 3.2 about the usage of Prefer: return=representation with status code 412

HTTP_REQUEST_ENTITY_TOO_LARGE (413)

See rfc 7231, section 6.5.11

This is returned when the body of the request is too large, such as when sending a file whose size has exceeded the maximum size limit.

For example:

HTTP/1.1 413 Payload Too Large
Retry-After: 3600
Content-Type: text/html
Content-Length: 52

<p>You exceeded your quota. Try again in an hour</p>

See also rfc 7231, section 7.1.3 on Retry-After header field.

See also 507 Insufficient Storage

HTTP_PAYLOAD_TOO_LARGE (413)

Same as previous. Used here for compatibility with HTTP::Status

HTTP_REQUEST_URI_TOO_LARGE (414)

See rfc 7231, section 6.5.12

Although there is no official limit to the size of an URI, some servers may implement a limit and return this status code when the URI exceeds it. Usually, it is recommended not to exceed 2048 bytes for an URI.

HTTP_UNSUPPORTED_MEDIA_TYPE (415)

See rfc 7231, section 6.5.13

This is returned when the server received a request body type it does not understand.

This status code may be returned even if the Content-Type header value is supported, because the server would still inspect the request body, such as with a broken JSON payload.

Usually, in those cases, the server would rather return 422 Unprocessable Entity

HTTP_RANGE_NOT_SATISFIABLE (416)

See rfc 7233, section 4.4 on Range Requests

This is returned when the client made a range request it did not understand.

Client can issue range request instead of downloading the entire file, which is helpful for large data.

HTTP_REQUEST_RANGE_NOT_SATISFIABLE (416)

Same as previous. Used here for compatibility with HTTP::Status

HTTP_EXPECTATION_FAILED (417)

See rfc 7231, section 6.5.14

This is returned when the server received an Expect header field value it did not understand.

For example:

PUT /some//big/file.mp4 HTTP/1.1
Host: www.example.org
Content-Type: video/mp4
Content-Length: 778043392
Expect: 100-continue

Then, the server could respond with the following:

HTTP/1.1 417 Expectation Failed
Server: Apache/2.4
Content-Type: text/plain
Content-Length: 30

We do not support 100-continue

See also rfc 7231, section 5.1.1 on the Expect header.

HTTP_I_AM_A_TEAPOT (418)

See rfc 2324 on HTCPC/1.0 1-april

This status code is not actually a real one, but one that was made by the IETF as an april-fools' joke, and it stuck. Attempts to remove it was met with strong resistance.

There has even been libraries developed to implement the HTCPC protocol.

HTTP_I_AM_A_TEA_POT (418)

Same as previous.

HTTP_MISDIRECTED_REQUEST (421)

See rfc 7540, section 9.1.2 on HTTP/2

This is returned when the web server received a request that was not intended for him.

For example:

GET /contact.html HTTP/1.1
Host: foo.example.org

HTTP/1.1 421 Misdirected Request
Content-Type: text/plain
Content-Length: 27

This host unsupported here.

HTTP_UNPROCESSABLE_ENTITY (422)

See rfc 4918, section 11.2

This is returned when the web server understood the request, but deemed the body content to not be processable.

For example:

POST /new-article HTTP/1.1
Content-Type: application/json
Content-Length: 26

{ "title": "Hello world!"}

Then, the web server could respond something like:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
Content-Length: 114

{
  "type" : "https://example.org/errors/missing-property",
  "status": 422,
  "title": "Missing property: body"
}

HTTP_LOCKED (423)

See rfc 4918 on WebDAV

This is returned under the WebDav protocol when one tries to make change to a locked resource.

HTTP_FAILED_DEPENDENCY (424)

See rfc 4918 on WebDAV

This is returned under the WebDav protocol when the processing of one of the resources failed.

HTTP_TOO_EARLY (425)

See rfc 8470, section 5.2 on Using Early Data in HTTP

This predominantly occurs during the TLS handshake to notify the client to retry a bit later once the TLS connection is up.

HTTP_NO_CODE (425)

Same as previous. Used here for compatibility with HTTP::Status

HTTP_UNORDERED_COLLECTION (425)

Same as previous. Used here for compatibility with HTTP::Status

HTTP_UPGRADE_REQUIRED (426)

See rfc 7231, section 6.5.15

This is returned to notify the client to use a newer version of the HTTP protocol.

HTTP_PRECONDITION_REQUIRED (428)

See rfc 6585, section 3 on Additional Codes

This is used when the web server requires the client to use condition requests, such as:

If-Match
If-None-Match
If-Modified-Since
If-Unmodified-Since
If-Range

HTTP_TOO_MANY_REQUESTS (429)

See rfc 6585, section 4 on Additional Codes

This is returned when the server needs to notify the client to slow down the number of requests. This is predominantly used for API, but not only.

For example:

HTTP/1.1 429 Too Many Requests
Content-Type: text/plain
Content-Length: 44
Retry-After: 3600

You exceeded the limit. Try again in an hour

HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE (431)

See rfc 6585, section 5 on Additional Codes

This is returned when the client issued a request containing HTTP header fields that are too big in size. Most likely culprit are the HTTP cookies.

HTTP_CONNECTION_CLOSED_WITHOUT_RESPONSE (444)

This is a non-standard status code used by some web servers, such as nginx, to instruct it to close the connection without sending a response back to the client, predominantly to deny malicious or malformed requests.

This status code is actually not seen by the client, but only appears in nginx log files.

See rfc 7725 on Legal Obstacles

This is returned when, for some legal reasons, the resource could not be served.

This status code has been chosen on purpose, for its relation with the book Fahrenheit 451 from Ray Bradbury. In his book, the central theme is the censorship of literature. The book title itself "Fahrenheit 451" refers to the temperature at which paper ignites, i.e. 451 Fahrenheit or 232° Celsius.

For example:

HTTP/1.1 451 Unavailable For Legal Reasons
Link: <https://example.org/legal>; rel="blocked-by"
Content-Type text/plain
Content-Length: 48

You are prohibited from accessing this resource.

HTTP_CLIENT_CLOSED_REQUEST (499)

This is a non-standard status code used by some web servers, such as nginx, when the client has closed the connection while the web server was still processing the request.

This status code is actually not seen by the client, but only appears in nginx log files.

HTTP_INTERNAL_SERVER_ERROR (500)

See rfc 7231, section 6.6.1

This is returned when an internal malfunction due to some bug of general processing error.

HTTP_NOT_IMPLEMENTED (501)

See rfc 7231, section 6.6.2

This is returned when the web server unexpectedly does not support certain features, although the request was itself acceptable.

HTTP_BAD_GATEWAY (502)

See rfc 7231, section 6.6.3

This is returned by proxy servers when the original target server is not operating properly and to notify the client of this.

HTTP_SERVICE_UNAVAILABLE (503)

See rfc 7231, section 6.6.4

This is returned when the web server is temporally incapable of processing the request, such as due to overload.

For example:

HTTP/1.1 503 Service Unavailable
Content-Type text/plain
Content-Length: 56
Retry-After: 1800

System overload! Give us some time to increase capacity.

HTTP_GATEWAY_TIME_OUT (504)

See rfc 7231, section 6.6.5

This is returned by a proxy server when the upstream target server is not responding in a timely manner.

HTTP_VERSION_NOT_SUPPORTED (505)

See rfc 7231, section 6.6.6

This is returned when the web server does not support the HTTP version submitted by the client.

For example:

GET / HTTP/4.0
Host: www.example.org

Then, the server would respond something like:

HTTP/1.1 505 HTTP Version Not Supported
Server: Apache/2.4
Date: Mon, 18 Apr 2022 15:23:35 GMT
Content-Type: text/plain
Content-Length: 30
Connection: close

505 HTTP Version Not Supported

HTTP_VARIANT_ALSO_VARIES (506)

See rfc 2295 on Transparant Ngttn

This is returned in the context of Transparent Content Negotiation when there is a server-side misconfiguration that leads the chosen variant itself to also engage in content negotiation, thus looping.

For example:

GET / HTTP/1.1
Host: www.example.org
Accept: text/html; image/png; text/*; q=0.9
Accept-Language: en-GB; en
Accept-Charset: UTF-8
Accept-Encoding: gzip, deflate, br

HTTP_INSUFFICIENT_STORAGE (507)

See rfc 4918, section 11.5 on WebDAV

This is returned in the context of WebDav protocol when a POST or PUT request leads to storing data, but the operations fails, because the resource is too large to fit on the remaining space on the server disk.

HTTP_LOOP_DETECTED (508)

See rfc 5842, section 7.2 on WebDAV bindings

This is returned in the context of WebDav when the target resource is looping.

HTTP_BANDWIDTH_LIMIT_EXCEEDED (509)

This is returned by some web servers when the amount of bandwidth consumed exceeded the maximum possible.

HTTP_NOT_EXTENDED (510)

See rfc 2774, section 6 on Extension Framework

This is returned by the web server who expected the client to use an extended http feature, but did not.

This is not widely implemented.

HTTP_NETWORK_AUTHENTICATION_REQUIRED (511)

See rfc 6585, section 6.1 on Additional Codes

This is returned by web server on private network to notify the client that a prior authentication is required to be able to browse the web. This is most likely used in location with private WiFi, such as lounges.

HTTP_NETWORK_CONNECT_TIMEOUT_ERROR (599)

This is returned by some proxy servers to signal a network connect timeout behind the proxy and the upstream target server.

This is not part of the standard.

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

IANA HTTP codes list, rfc7231

HTTP::Promise, HTTP::Promise::Request, HTTP::Promise::Response, HTTP::Promise::Message, HTTP::Promise::Entity, HTTP::Promise::Headers, HTTP::Promise::Body, HTTP::Promise::Body::Form, HTTP::Promise::Body::Form::Data, HTTP::Promise::Body::Form::Field, HTTP::Promise::Status, HTTP::Promise::MIME, HTTP::Promise::Parser, HTTP::Promise::IO, HTTP::Promise::Stream, HTTP::Promise::Exception

COPYRIGHT & LICENSE

Copyright(c) 2022 DEGUEST Pte. Ltd.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.