Error Handling¶
When it comes to error handling, you can always directly set the error
status, appropriate response headers, and error body using the resp
object. However, Falcon tries to make things a little easier by
providing a set of error classes you can raise when something goes
wrong. All of these classes inherit from HTTPError
.
Falcon will convert any instance or subclass of HTTPError
raised by a responder, hook, or middleware component into an appropriate
HTTP response. The default error serializer supports both JSON and XML.
If the client indicates acceptance of both JSON and XML with equal
weight, JSON will be chosen. Other media types may be supported by
overriding the default serializer via
set_error_serializer()
.
Note
If a custom media type is used and the type includes a “+json” or “+xml” suffix, the default serializer will convert the error to JSON or XML, respectively.
To customize what data is passed to the serializer, subclass
HTTPError
or any of its child classes, and override the
to_dict()
method. To also support XML, override the
to_xml()
method. For example:
class HTTPNotAcceptable(falcon.HTTPNotAcceptable):
def __init__(self, acceptable):
description = (
'Please see "acceptable" for a list of media types '
'and profiles that are currently supported.'
)
super().__init__(description=description)
self._acceptable = acceptable
def to_dict(self, obj_type=dict):
result = super().to_dict(obj_type)
result['acceptable'] = self._acceptable
return result
All classes are available directly in the falcon
package namespace:
import falcon
class MessageResource:
def on_get(self, req, resp):
# -- snip --
raise falcon.HTTPBadRequest(
title="TTL Out of Range",
description="The message's TTL must be between 60 and 300 seconds, inclusive."
)
# -- snip --
import falcon
class MessageResource:
async def on_get(self, req, resp):
# -- snip --
raise falcon.HTTPBadRequest(
title="TTL Out of Range",
description="The message's TTL must be between 60 and 300 seconds, inclusive."
)
# -- snip --
Note also that any exception (not just instances of
HTTPError
) can be caught, logged, and otherwise handled
at the global level by registering one or more custom error handlers.
See also add_error_handler()
to learn more about this
feature.
Note
By default, any uncaught exceptions will return an HTTP 500 response and
log details of the exception to wsgi.errors
.
Base Class¶
- class falcon.HTTPError(status, title=None, description=None, headers=None, href=None, href_text=None, code=None)[source]¶
Represents a generic HTTP error.
Raise an instance or subclass of
HTTPError
to have Falcon return a formatted error response and an appropriate HTTP status code to the client when something goes wrong. JSON and XML media types are supported by default.To customize the error presentation, implement a custom error serializer and set it on the
App
instance viaset_error_serializer()
.To customize what data is passed to the serializer, subclass
HTTPError
and override theto_dict()
method (to_json()
is implemented viato_dict()
). To also support XML, override theto_xml()
method.Note
status
is the only positional argument allowed, the other arguments should be used as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.- Parameters:
status (str) – HTTP status code and text, such as “400 Bad Request”
- Keyword Arguments:
title (str) – Human-friendly error title. If not provided, defaults to the HTTP status line as determined by the
status
argument.description (str) – Human-friendly description of the error, along with a helpful suggestion or two (default
None
).A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘App documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- code¶
An internal application code that a user can reference when requesting support for the error.
- Type:
- to_dict(obj_type=<class 'dict'>)[source]¶
Return a basic dictionary representing the error.
This method can be useful when serializing the error to hash-like media types, such as YAML, JSON, and MessagePack.
- Parameters:
obj_type – A dict-like type that will be used to store the error information (default
dict
).- Returns:
A dictionary populated with the error’s title, description, etc.
- Return type:
- to_json(handler=None)[source]¶
Return a JSON representation of the error.
- Parameters:
handler – Handler object that will be used to serialize the representation of this error to JSON. When not provided, a default handler using the builtin JSON library will be used (default
None
).- Returns:
A JSON document for the error.
- Return type:
Predefined Errors¶
- class falcon.HTTPBadRequest(title=None, description=None, headers=None, **kwargs)[source]¶
400 Bad Request.
The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
(See also: RFC 7231, Section 6.5.1)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘400 Bad Request’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPInvalidHeader(msg, header_name, headers=None, **kwargs)[source]¶
400 Bad Request.
One of the headers in the request is invalid.
Note
msg
andheader_name
are the only positional argument allowed, the other arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.- Parameters:
- Keyword Arguments:
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPMissingHeader(header_name, headers=None, **kwargs)[source]¶
400 Bad Request.
A header is missing from the request.
Note
header_name
is the only positional argument allowed, the other arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.- Parameters:
header_name (str) – The name of the missing header.
- Keyword Arguments:
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPInvalidParam(msg, param_name, headers=None, **kwargs)[source]¶
400 Bad Request.
A parameter in the request is invalid. This error may refer to a parameter in a query string, form, or document that was submitted with the request.
Note
msg
andparam_name
are the only positional argument allowed, the other arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.- Parameters:
- Keyword Arguments:
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPMissingParam(param_name, headers=None, **kwargs)[source]¶
400 Bad Request.
A parameter is missing from the request. This error may refer to a parameter in a query string, form, or document that was submitted with the request.
Note
param_name
is the only positional argument allowed, the other arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.- Parameters:
param_name (str) – The name of the missing parameter.
- Keyword Arguments:
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPUnauthorized(title=None, description=None, headers=None, challenges=None, **kwargs)[source]¶
401 Unauthorized.
The request has not been applied because it lacks valid authentication credentials for the target resource.
The server generating a 401 response MUST send a WWW-Authenticate header field containing at least one challenge applicable to the target resource.
If the request included authentication credentials, then the 401 response indicates that authorization has been refused for those credentials. The user agent MAY repeat the request with a new or replaced Authorization header field. If the 401 response contains the same challenge as the prior response, and the user agent has already attempted authentication at least once, then the user agent SHOULD present the enclosed representation to the user, since it usually contains relevant diagnostic information.
(See also: RFC 7235, Section 3.1)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘401 Unauthorized’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.challenges (iterable of str) –
One or more authentication challenges to use as the value of the WWW-Authenticate header in the response.
Note
The existing value of the WWW-Authenticate in headers will be overridden by this value
(See also: RFC 7235, Section 2.1)
href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPForbidden(title=None, description=None, headers=None, **kwargs)[source]¶
403 Forbidden.
The server understood the request but refuses to authorize it.
A server that wishes to make public why the request has been forbidden can describe that reason in the response payload (if any).
If authentication credentials were provided in the request, the server considers them insufficient to grant access. The client SHOULD NOT automatically repeat the request with the same credentials. The client MAY repeat the request with new or different credentials. However, a request might be forbidden for reasons unrelated to the credentials.
An origin server that wishes to “hide” the current existence of a forbidden target resource MAY instead respond with a status code of 404 Not Found.
(See also: RFC 7231, Section 6.5.4)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘403 Forbidden’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPNotFound(title=None, description=None, headers=None, **kwargs)[source]¶
404 Not Found.
The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
A 404 status code does not indicate whether this lack of representation is temporary or permanent; the 410 Gone status code is preferred over 404 if the origin server knows, presumably through some configurable means, that the condition is likely to be permanent.
A 404 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls.
(See also: RFC 7231, Section 6.5.3)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Human-friendly error title. If not provided, and description is also not provided, no body will be included in the response.
description (str) – Human-friendly description of the error, along with a helpful suggestion or two (default
None
).A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPRouteNotFound(title=None, description=None, headers=None, **kwargs)[source]¶
404 Not Found.
The request did not match any routes configured for the application.
This subclass of
HTTPNotFound
is raised by the framework to provide a default 404 response when no route matches the request. This behavior can be customized by registering a custom error handler forHTTPRouteNotFound
.Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Human-friendly error title. If not provided, and description is also not provided, no body will be included in the response.
description (str) – Human-friendly description of the error, along with a helpful suggestion or two (default
None
).A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPMethodNotAllowed(allowed_methods, title=None, description=None, headers=None, **kwargs)[source]¶
405 Method Not Allowed.
The method received in the request-line is known by the origin server but not supported by the target resource.
The origin server MUST generate an Allow header field in a 405 response containing a list of the target resource’s currently supported methods.
A 405 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls.
(See also: RFC 7231, Section 6.5.5)
Note
allowed_methods
is the only positional argument allowed, the other arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.- Parameters:
allowed_methods (list of str) –
Allowed HTTP methods for this resource (e.g.,
['GET', 'POST', 'HEAD']
).Note
If previously set, the Allow response header will be overridden by this value.
- Keyword Arguments:
title (str) – Human-friendly error title. If not provided, and description is also not provided, no body will be included in the response.
description (str) – Human-friendly description of the error, along with a helpful suggestion or two (default
None
).A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPNotAcceptable(title=None, description=None, headers=None, **kwargs)[source]¶
406 Not Acceptable.
The target resource does not have a current representation that would be acceptable to the user agent, according to the proactive negotiation header fields received in the request, and the server is unwilling to supply a default representation.
The server SHOULD generate a payload containing a list of available representation characteristics and corresponding resource identifiers from which the user or user agent can choose the one most appropriate. A user agent MAY automatically select the most appropriate choice from that list. However, this specification does not define any standard for such automatic selection, as described in RFC 7231, Section 6.4.1
(See also: RFC 7231, Section 6.5.6)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPConflict(title=None, description=None, headers=None, **kwargs)[source]¶
409 Conflict.
The request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request.
The server SHOULD generate a payload that includes enough information for a user to recognize the source of the conflict.
Conflicts are most likely to occur in response to a PUT request. For example, if versioning were being used and the representation being PUT included changes to a resource that conflict with those made by an earlier (third-party) request, the origin server might use a 409 response to indicate that it can’t complete the request. In this case, the response representation would likely contain information useful for merging the differences based on the revision history.
(See also: RFC 7231, Section 6.5.8)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘409 Conflict’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPGone(title=None, description=None, headers=None, **kwargs)[source]¶
410 Gone.
The target resource is no longer available at the origin server and this condition is likely to be permanent.
If the origin server does not know, or has no facility to determine, whether or not the condition is permanent, the status code 404 Not Found ought to be used instead.
The 410 response is primarily intended to assist the task of web maintenance by notifying the recipient that the resource is intentionally unavailable and that the server owners desire that remote links to that resource be removed. Such an event is common for limited-time, promotional services and for resources belonging to individuals no longer associated with the origin server’s site. It is not necessary to mark all permanently unavailable resources as “gone” or to keep the mark for any length of time – that is left to the discretion of the server owner.
A 410 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls.
(See also: RFC 7231, Section 6.5.9)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Human-friendly error title. If not provided, and description is also not provided, no body will be included in the response.
description (str) – Human-friendly description of the error, along with a helpful suggestion or two (default
None
).A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPLengthRequired(title=None, description=None, headers=None, **kwargs)[source]¶
411 Length Required.
The server refuses to accept the request without a defined Content- Length.
The client MAY repeat the request if it adds a valid Content-Length header field containing the length of the message body in the request message.
(See also: RFC 7231, Section 6.5.10)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘411 Length Required’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPPreconditionFailed(title=None, description=None, headers=None, **kwargs)[source]¶
412 Precondition Failed.
One or more conditions given in the request header fields evaluated to false when tested on the server.
This response code allows the client to place preconditions on the current resource state (its current representations and metadata) and, thus, prevent the request method from being applied if the target resource is in an unexpected state.
(See also: RFC 7232, Section 4.2)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘412 Precondition Failed’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPPayloadTooLarge(title=None, description=None, retry_after=None, headers=None, **kwargs)[source]¶
413 Payload Too Large.
The server is refusing to process a request because the request payload is larger than the server is willing or able to process.
The server MAY close the connection to prevent the client from continuing the request.
If the condition is temporary, the server SHOULD generate a Retry- After header field to indicate that it is temporary and after what time the client MAY try again.
(See also: RFC 7231, Section 6.5.11)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘413 Payload Too Large’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.retry_after (datetime or int) –
Value for the Retry-After header. If a
datetime
object, will serialize as an HTTP date. Otherwise, a non-negativeint
is expected, representing the number of seconds to wait.Note
The existing value of the Retry-After in headers will be overridden by this value
href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPUriTooLong(title=None, description=None, headers=None, **kwargs)[source]¶
414 URI Too Long.
The server is refusing to service the request because the request- target is longer than the server is willing to interpret.
This rare condition is only likely to occur when a client has improperly converted a POST request to a GET request with long query information, when the client has descended into a “black hole” of redirection (e.g., a redirected URI prefix that points to a suffix of itself) or when the server is under attack by a client attempting to exploit potential security holes.
A 414 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls.
(See also: RFC 7231, Section 6.5.12)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘414 URI Too Long’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two (default
None
).A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPUnsupportedMediaType(title=None, description=None, headers=None, **kwargs)[source]¶
415 Unsupported Media Type.
The origin server is refusing to service the request because the payload is in a format not supported by this method on the target resource.
The format problem might be due to the request’s indicated Content- Type or Content-Encoding, or as a result of inspecting the data directly.
(See also: RFC 7231, Section 6.5.13)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘415 Unsupported Media Type’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPRangeNotSatisfiable(resource_length, title=None, description=None, headers=None, **kwargs)[source]¶
416 Range Not Satisfiable.
None of the ranges in the request’s Range header field overlap the current extent of the selected resource or that the set of ranges requested has been rejected due to invalid ranges or an excessive request of small or overlapping ranges.
For byte ranges, failing to overlap the current extent means that the first-byte-pos of all of the byte-range-spec values were greater than the current length of the selected representation. When this status code is generated in response to a byte-range request, the sender SHOULD generate a Content-Range header field specifying the current length of the selected representation.
(See also: RFC 7233, Section 4.4)
Note
resource_length
is the only positional argument allowed, the other arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.- Parameters:
resource_length –
The maximum value for the last-byte-pos of a range request. Used to set the Content-Range header.
Note
The existing value of the Content-Range in headers will be overridden by this value
- Keyword Arguments:
title (str) – Error title (default ‘416 Range Not Satisfiable’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPUnprocessableEntity(title=None, description=None, headers=None, **kwargs)[source]¶
422 Unprocessable Entity.
The server understands the content type of the request entity (hence a 415 Unsupported Media Type status code is inappropriate), and the syntax of the request entity is correct (thus a 400 Bad Request status code is inappropriate) but was unable to process the contained instructions.
For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.
(See also: RFC 4918, Section 11.2)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘422 Unprocessable Entity’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPLocked(title=None, description=None, headers=None, **kwargs)[source]¶
423 Locked.
The 423 (Locked) status code means the source or destination resource of a method is locked. This response SHOULD contain an appropriate precondition or postcondition code, such as ‘lock-token-submitted’ or ‘no-conflicting-lock’.
(See also: RFC 4918, Section 11.3)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘423 Locked’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPFailedDependency(title=None, description=None, headers=None, **kwargs)[source]¶
424 Failed Dependency.
The 424 (Failed Dependency) status code means that the method could not be performed on the resource because the requested action depended on another action and that action failed.
(See also: RFC 4918, Section 11.4)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘424 Failed Dependency’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPPreconditionRequired(title=None, description=None, headers=None, **kwargs)[source]¶
428 Precondition Required.
The 428 status code indicates that the origin server requires the request to be conditional.
Its typical use is to avoid the “lost update” problem, where a client GETs a resource’s state, modifies it, and PUTs it back to the server, when meanwhile a third party has modified the state on the server, leading to a conflict. By requiring requests to be conditional, the server can assure that clients are working with the correct copies.
Responses using this status code SHOULD explain how to resubmit the request successfully.
(See also: RFC 6585, Section 3)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘428 Precondition Required’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPTooManyRequests(title=None, description=None, headers=None, retry_after=None, **kwargs)[source]¶
429 Too Many Requests.
The user has sent too many requests in a given amount of time (“rate limiting”).
The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request.
Responses with the 429 status code MUST NOT be stored by a cache.
(See also: RFC 6585, Section 4)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘429 Too Many Requests’).
description (str) – Human-friendly description of the rate limit that was exceeded.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.retry_after (datetime or int) –
Value for the Retry-After header. If a
datetime
object, will serialize as an HTTP date. Otherwise, a non-negativeint
is expected, representing the number of seconds to wait.Note
The existing value of the Retry-After in headers will be overridden by this value
href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPRequestHeaderFieldsTooLarge(title=None, description=None, headers=None, **kwargs)[source]¶
431 Request Header Fields Too Large.
The 431 status code indicates that the server is unwilling to process the request because its header fields are too large. The request MAY be resubmitted after reducing the size of the request header fields.
It can be used both when the set of request header fields in total is too large, and when a single header field is at fault. In the latter case, the response representation SHOULD specify which header field was too large.
Responses with the 431 status code MUST NOT be stored by a cache.
(See also: RFC 6585, Section 5)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘431 Request Header Fields Too Large’).
description (str) – Human-friendly description of the rate limit that was exceeded.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
451 Unavailable For Legal Reasons.
The server is denying access to the resource as a consequence of a legal demand.
The server in question might not be an origin server. This type of legal demand typically most directly affects the operations of ISPs and search engines.
Responses using this status code SHOULD include an explanation, in the response body, of the details of the legal demand: the party making it, the applicable legislation or regulation, and what classes of person and resource it applies to.
Note that in many cases clients can still access the denied resource by using technical countermeasures such as a VPN or the Tor network.
A 451 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls.
(See also: RFC 7725, Section 3)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘451 Unavailable For Legal Reasons’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two (default
None
).A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPInternalServerError(title=None, description=None, headers=None, **kwargs)[source]¶
500 Internal Server Error.
The server encountered an unexpected condition that prevented it from fulfilling the request.
(See also: RFC 7231, Section 6.6.1)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘500 Internal Server Error’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPNotImplemented(title=None, description=None, headers=None, **kwargs)[source]¶
501 Not Implemented.
The 501 (Not Implemented) status code indicates that the server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.
A 501 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls as described in RFC 7234, Section 4.2.2.
(See also: RFC 7231, Section 6.6.2)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘500 Internal Server Error’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPBadGateway(title=None, description=None, headers=None, **kwargs)[source]¶
502 Bad Gateway.
The server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while attempting to fulfill the request.
(See also: RFC 7231, Section 6.6.3)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘502 Bad Gateway’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
503 Service Unavailable.
The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.
The server MAY send a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.
Note: The existence of the 503 status code does not imply that a server has to use it when becoming overloaded. Some servers might simply refuse the connection.
(See also: RFC 7231, Section 6.6.4)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘503 Service Unavailable’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.retry_after (datetime or int) –
Value for the Retry-After header. If a
datetime
object, will serialize as an HTTP date. Otherwise, a non-negativeint
is expected, representing the number of seconds to wait.Note
The existing value of the Retry-After in headers will be overridden by this value
href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPGatewayTimeout(title=None, description=None, headers=None, **kwargs)[source]¶
504 Gateway Timeout.
The 504 (Gateway Timeout) status code indicates that the server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to access in order to complete the request.
(See also: RFC 7231, Section 6.6.5)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘503 Service Unavailable’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPVersionNotSupported(title=None, description=None, headers=None, **kwargs)[source]¶
505 HTTP Version Not Supported.
The 505 (HTTP Version Not Supported) status code indicates that the server does not support, or refuses to support, the major version of HTTP that was used in the request message. The server is indicating that it is unable or unwilling to complete the request using the same major version as the client (as described in RFC 7230, Section 2.6), other than with this error message. The server SHOULD generate a representation for the 505 response that describes why that version is not supported and what other protocols are supported by that server.
(See also: RFC 7231, Section 6.6.6)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘503 Service Unavailable’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPInsufficientStorage(title=None, description=None, headers=None, **kwargs)[source]¶
507 Insufficient Storage.
The 507 (Insufficient Storage) status code means the method could not be performed on the resource because the server is unable to store the representation needed to successfully complete the request. This condition is considered to be temporary. If the request that received this status code was the result of a user action, the request MUST NOT be repeated until it is requested by a separate user action.
(See also: RFC 4918, Section 11.5)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘507 Insufficient Storage’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPLoopDetected(title=None, description=None, headers=None, **kwargs)[source]¶
508 Loop Detected.
The 508 (Loop Detected) status code indicates that the server terminated an operation because it encountered an infinite loop while processing a request with “Depth: infinity”. This status indicates that the entire operation failed.
(See also: RFC 5842, Section 7.2)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘508 Loop Detected’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.HTTPNetworkAuthenticationRequired(title=None, description=None, headers=None, **kwargs)[source]¶
511 Network Authentication Required.
The 511 status code indicates that the client needs to authenticate to gain network access.
The response representation SHOULD contain a link to a resource that allows the user to submit credentials.
Note that the 511 response SHOULD NOT contain a challenge or the authentication interface itself, because clients would show the interface as being associated with the originally requested URL, which may cause confusion.
The 511 status SHOULD NOT be generated by origin servers; it is intended for use by intercepting proxies that are interposed as a means of controlling access to the network.
Responses with the 511 status code MUST NOT be stored by a cache.
(See also: RFC 6585, Section 6)
Note
All the arguments should be passed as keyword only. Using them as positional arguments will raise a deprecation warning and will result in an error in a future version of falcon.
- Keyword Arguments:
title (str) – Error title (default ‘511 Network Authentication Required’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.MediaNotFoundError(media_type, **kwargs)[source]¶
400 Bad Request.
Exception raised by a media handler when trying to parse an empty body.
Note
Some media handlers, like the one for URL-encoded forms, allow an empty body. In these cases this exception will not be raised.
- Parameters:
media_type (str) – The media type that was expected.
- Keyword Arguments:
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.MediaMalformedError(media_type, **kwargs)[source]¶
400 Bad Request.
Exception raised by a media handler when trying to parse a malformed body. The cause of this exception, if any, is stored in the
__cause__
attribute using the “raise … from” form when raising.- Parameters:
media_type (str) – The media type that was expected.
- Keyword Arguments:
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).
- class falcon.MediaValidationError(*, title=None, description=None, headers=None, **kwargs)[source]¶
400 Bad Request.
Request media is invalid. This exception is raised by a media validator (such as
jsonschema.validate
) whenreq.media
is successfully deserialized, but fails to validate against the configured schema.The cause of this exception, if any, is stored in the
__cause__
attribute using the “raise … from” form when raising.Note
All the arguments must be passed as keyword only.
- Keyword Arguments:
title (str) – Error title (default ‘400 Bad Request’).
description (str) – Human-friendly description of the error, along with a helpful suggestion or two.
A
dict
of header names and values to set, or alist
of (name, value) tuples. Both name and value must be of typestr
orStringType
, and only character values 0x00 through 0xFF may be used on platforms that use wide characters.Note
The Content-Type header, if present, will be overridden. If you wish to return custom error messages, you can create your own HTTP error class, and install an error handler to convert it into an appropriate HTTP response for the client
Note
Falcon can process a list of
tuple
slightly faster than adict
.href (str) – A URL someone can visit to find out more information (default
None
). Unicode characters are percent-encoded.href_text (str) – If href is given, use this as the friendly title/description for the link (default ‘API documentation for this error’).
code (int) – An internal code that customers can reference in their support request or to help them when searching for knowledge base articles related to this error (default
None
).