Apache2-API
view release on metacpan or search on metacpan
lib/Apache2/API/Status.pm view on Meta::CPAN
=head2 is_info
Returns true if the 3-digits code provided is between 100 and 200
=head2 is_redirect
Returns true if the 3-digits code provided is between 300 and 400
=head2 is_server_error
Returns true if the 3-digits code provided is between 500 and 600
=head2 is_success
Returns true if the 3-digits code provided is between 200 and 300
=head2 status_message
Provided with a 3-digits HTTP code and an optional language code such as C<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. L<Apache2::API/reply> uses 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 C<en_GB>.
See L</supported_languages> for the supported languages.
=head2 status_to_type
Provided with a status code, such as C<404>, and this returns a status type such as C<not_found>.
This is used to build a rfc9457 compliant error.
=head2 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.
=head1 CONSTANTS
The following constants can be exported. You can use the C<:all> tag to export them all, such as:
use Apache2::API::Status qw( :all );
or you can use the tag C<: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
=head2 HTTP_CONTINUE (100)
See L<rfc 7231, section 5.1.1|https://tools.ietf.org/html/rfc7231#section-5.1.1> and section L<6.2.1|https://tools.ietf.org/html/rfc7231#section-6.2.1> and L<Mozilla docs|https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/100>
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 C<PUT> request (here a 74...
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 C<413 Request Entity Too Large> or C<405 Method Not Allowed> or even C<401 Unauthorized>, or even a C<417 Expectation Failed> if it does not support this feature.
A response C<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 C<Expect: 100-continue>
In some REST API implementation, the server response code C<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.
=head2 HTTP_SWITCHING_PROTOCOLS (101)
See L<rfc7231, section 6.2.2|https://tools.ietf.org/html/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 L<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
=head2 HTTP_PROCESSING (102)
See L<rfc 2518 on WebDAV|https://tools.ietf.org/html/rfc2518>
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.
=head2 HTTP_EARLY_HINTS (103)
See L<rfc 8297 on Indicating Hints|https://tools.ietf.org/html/rfc8297>
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
=head2 HTTP_OK (200)
See L<rfc7231, section 6.3.1|https://datatracker.ietf.org/doc/html/rfc7231#section-6.3.1>
This is returned to inform the request has succeeded. It can also alternatively be C<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>
=head2 HTTP_CREATED (201)
See L<rfc7231, section 6.3.2|https://datatracker.ietf.org/doc/html/rfc7231#section-6.3.2>
This is returned to notify the related resource has been created, most likely by a C<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"
=head2 HTTP_ACCEPTED (202)
See L<rfc7231, section 6.3.3|https://tools.ietf.org/html/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
=head2 HTTP_NON_AUTHORITATIVE (203)
See L<rfc 7231, section 6.3.4|https://tools.ietf.org/html/rfc7231#section-6.3.4>
This would typically be returned by an HTTP proxy after it has made some change to the content.
=head2 HTTP_NO_CONTENT (204)
L<See rfc 7231, section 6.3.5|https://tools.ietf.org/html/rfc7231#section-6.3.5>
This is returned when the request was processed successfully, but there is no body content returned.
=head2 HTTP_RESET_CONTENT (205)
L<See rfc 7231, section 6.3.6|https://tools.ietf.org/html/rfc7231#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.
=head2 HTTP_PARTIAL_CONTENT (206)
See L<rfc 7233 on Range Requests|https://tools.ietf.org/html/rfc7233>
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
=head2 HTTP_MULTI_STATUS (207)
lib/Apache2/API/Status.pm view on Meta::CPAN
=head2 HTTP_BAD_REQUEST (400)
See L<rfc 7231, section 6.5.1|https://tools.ietf.org/html/rfc7231#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 C<4xx> code are not suitable.
=head2 HTTP_UNAUTHORIZED (401)
See L<rfc 7235, section 3.1 on Authentication|https://tools.ietf.org/html/rfc7235#section-3.1>
See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401>
This is returned to indicate to the client it must authenticate first before issuing the request.
See also status code C<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 C<aladdin> with password C<opensesame> would result in the following request:
GET / HTTP/1.1
Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
See also L<Mozilla documentation on Authorization header|https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization>
=head2 HTTP_PAYMENT_REQUIRED (402)
See L<rfc 7231, section 6.5.2|https://tools.ietf.org/html/rfc7231#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.
=head2 HTTP_FORBIDDEN (403)
See L<rfc 7231, section 6.5.3|https://tools.ietf.org/html/rfc7231#section-6.5.3>
See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403>
This is returned to indicate the client is barred from accessing the resource.
This is different from C<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 C<PUT> instead of C<GET> method.
=head2 HTTP_NOT_FOUND (404)
See L<rfc 7231, section 6.5.4|https://tools.ietf.org/html/rfc7231#section-6.5.4>
See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404>
This is returned to indicate the resource does not exist anymore.
=head2 HTTP_METHOD_NOT_ALLOWED (405)
See L<rfc 7231, section 6.5.5|https://tools.ietf.org/html/rfc7231#section-6.5.5>
This is returned to indicate the client it used a L<method|https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods> not allowed, such as using C<PUT> instead of C<GET>. The server can point out the supported methods with the C<Allow> header, such a...
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>
=head2 HTTP_NOT_ACCEPTABLE (406)
See L<rfc 7231, section 6.5.6|https://tools.ietf.org/html/rfc7231#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 L<Accept|https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept>, L<Accept-Charset|https://developer.mozilla.org/e...
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:
=head2 HTTP_PROXY_AUTHENTICATION_REQUIRED (407)
See L<rfc 7235, section 3.2 on Authentication|https://tools.ietf.org/html/rfc7235#section-3.2>
This is returned to indicate the proxy used requires authentication. This is similar to the status code C<401 Unauthorized>.
=head2 HTTP_REQUEST_TIME_OUT (408)
See L<rfc 7231, section 6.5.7|https://tools.ietf.org/html/rfc7231#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
=head2 HTTP_CONFLICT (409)
See L<rfc 7231, section 6.5.8|https://tools.ietf.org/html/rfc7231#section-6.5.8>
This is returned to indicate a request conflict with the current state of the target resource, such as uploading with C<PUT> a file older than the remote one.
=head2 HTTP_GONE (410)
See L<rfc 7231, section 6.5.9|https://tools.ietf.org/html/rfc7231#section-6.5.9>
This is returned to indicate that the target resource is gone permanently. The subtle difference with the status code C<404> is that with C<404>, the resource may be only temporally unavailable whereas with C<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.
=head2 HTTP_LENGTH_REQUIRED (411)
See L<rfc 7231, section 6.5.10|https://tools.ietf.org/html/rfc7231#section-6.5.10>
This is returned when the C<Content-Length> header was not provided by the client and the server requires it to be present. Most servers can do without.
=head2 HTTP_PRECONDITION_FAILED (412)
See L<rfc 7232 on Conditional Request|https://tools.ietf.org/html/rfc7232>
This is returned when some preconditions set by the client could not be met.
For example:
Issuing a C<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 C<Prefer> header, the servers will return the current state of the resource, thus saving a round of request with a C<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 L<rfc 7240 about the Prefer header field|https://tools.ietf.org/html/rfc7240> and L<rfc 8144, Section 3.2|https://tools.ietf.org/html/rfc8144#section-3.2> about the usage of C<Prefer: return=representation> with status code C<412>
=head2 HTTP_REQUEST_ENTITY_TOO_LARGE (413)
See L<rfc 7231, section 6.5.11|https://tools.ietf.org/html/rfc7231#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 L<rfc 7231, section 7.1.3|https://tools.ietf.org/html/rfc7231#section-7.1.3> on C<Retry-After> header field.
See also C<507 Insufficient Storage>
=head2 HTTP_PAYLOAD_TOO_LARGE (413)
Same as previous. Used here for compatibility with C<HTTP::Status>
=head2 HTTP_REQUEST_URI_TOO_LARGE (414)
See L<rfc 7231, section 6.5.12|https://tools.ietf.org/html/rfc7231#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.
=head2 HTTP_UNSUPPORTED_MEDIA_TYPE (415)
See L<rfc 7231, section 6.5.13|https://tools.ietf.org/html/rfc7231#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 C<Content-Type> header value is supported, because the server would still inspect the request body, such as with a broken C<JSON> payload.
Usually, in those cases, the server would rather return C<422 Unprocessable Entity>
=head2 HTTP_RANGE_NOT_SATISFIABLE (416)
See L<rfc 7233, section 4.4 on Range Requests|https://tools.ietf.org/html/rfc7233#section-4.4>
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.
=head2 HTTP_REQUEST_RANGE_NOT_SATISFIABLE (416)
Same as previous. Used here for compatibility with C<HTTP::Status>
=head2 HTTP_EXPECTATION_FAILED (417)
See L<rfc 7231, section 6.5.14|https://tools.ietf.org/html/rfc7231#section-6.5.14>
This is returned when the server received an C<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 L<rfc 7231, section 5.1.1|https://tools.ietf.org/html/rfc7231#section-5.1.1> on the C<Expect> header.
=head2 HTTP_I_AM_A_TEAPOT (418)
See L<rfc 2324 on HTCPC/1.0 1-april|https://tools.ietf.org/html/rfc2324>
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 L<strong resistance|https://save418.com/>.
There has even been L<libraries developed|https://github.com/dkundel/htcpcp-delonghi> to implement the L<HTCPC protocol|https://github.com/HyperTextCoffeePot/HyperTextCoffeePot>.
=head2 HTTP_I_AM_A_TEA_POT (418)
Same as previous.
=head2 HTTP_MISDIRECTED_REQUEST (421)
See L<rfc 7540, section 9.1.2 on HTTP/2|https://tools.ietf.org/html/rfc7540#section-9.1.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.
=head2 HTTP_UNPROCESSABLE_ENTITY (422)
See L<rfc 4918, section 11.2|https://tools.ietf.org/html/rfc4918#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:
lib/Apache2/API/Status.pm view on Meta::CPAN
See L<rfc 7231, section 6.6.4|https://tools.ietf.org/html/rfc7231#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.
=head2 HTTP_GATEWAY_TIME_OUT (504)
See L<rfc 7231, section 6.6.5|https://tools.ietf.org/html/rfc7231#section-6.6.5>
This is returned by a proxy server when the upstream target server is not responding in a timely manner.
=head2 HTTP_VERSION_NOT_SUPPORTED (505)
See L<rfc 7231, section 6.6.6|https://tools.ietf.org/html/rfc7231#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
=head2 HTTP_VARIANT_ALSO_VARIES (506)
See L<rfc 2295 on Transparant Ngttn|https://tools.ietf.org/html/rfc2295>
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
=head2 HTTP_INSUFFICIENT_STORAGE (507)
See L<rfc 4918, section 11.5 on WebDAV|https://tools.ietf.org/html/rfc4918#section-11.5>
This is returned in the context of WebDav protocol when a C<POST> or C<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.
=head2 HTTP_LOOP_DETECTED (508)
See L<rfc 5842, section 7.2 on WebDAV bindings|https://tools.ietf.org/html/rfc5842#section-7.2>
This is returned in the context of WebDav when the target resource is looping.
=head2 HTTP_BANDWIDTH_LIMIT_EXCEEDED (509)
This is returned by some web servers when the amount of bandwidth consumed exceeded the maximum possible.
=head2 HTTP_NOT_EXTENDED (510)
See L<rfc 2774, section 6 on Extension Framework|https://tools.ietf.org/html/rfc2774#section-6>
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.
=head2 HTTP_NETWORK_AUTHENTICATION_REQUIRED (511)
See L<rfc 6585, section 6.1 on Additional Codes|https://tools.ietf.org/html/rfc6585#section-6.1>
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.
=head2 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.
=head1 APACHE CONSTANTS
This module adds the following missing L<Apache2::Const> constants for completeness:
=head2 Apache2::Const::EARLY_HINTS
HTTP code 103
=head2 Apache2::Const::I_AM_A_TEA_POT
HTTP code 418
=head2 Apache2::Const::MISDIRECTED_REQUEST
HTTP code 421
=head2 Apache2::Const::TOO_EARLY
HTTP code 425
=head2 Apache2::Const::CONNECTION_CLOSED_WITHOUT_RESPONSE
HTTP code 444
=head2 Apache2::Const::UNAVAILABLE_FOR_LEGAL_REASONS
HTTP code 451
=head2 Apache2::Const::CLIENT_CLOSED_REQUEST
( run in 0.862 second using v1.01-cache-2.11-cpan-56fb94df46f )