Exceptions¶
rn_forge.web.exceptions
¶
Typed exceptions mapped to HTTP problems by the default registry.
AuthenticationFailed(message, *message_args, error_code=-1, **error_data)
¶
Bases: WebError
No credentials were supplied, or they failed verification (401).
The message carries the reason for the binding to log; it must never reach
the response body, which renders :data:~rn_forge.web.auth.AUTH_FAILED_DETAIL.
The response carries a WWW-Authenticate challenge unless
:attr:challenge is false.
challenge = True
class-attribute
¶
Whether the 401 response carries a WWW-Authenticate challenge.
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
ContentTooLarge(message, *message_args, error_code=-1, **error_data)
¶
Bases: WebError
The request body exceeds the configured size limit (413).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
CsrfFailed(message, *message_args, error_code=-1, **error_data)
¶
Bases: WebError
The CSRF token or origin check rejected the request (403).
Not a :class:PermissionDenied, and rendered as its own problem type. The
message carries the reason for the
binding to log; it must never reach the response body, which renders
:data:~rn_forge.web.auth.CSRF_FAILED_DETAIL.
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
DomainConflict(message, *message_args, error_code=-1, **error_data)
¶
Bases: WebError
The request conflicts with the current state of the resource (409).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
IdempotencyKeyInFlight(message, *message_args, error_code=-1, **error_data)
¶
Bases: WebError
The idempotency key was claimed and its original request has not completed (409).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
IdempotencyKeyRequired(message, *message_args, error_code=-1, **error_data)
¶
Bases: WebError
The endpoint requires an Idempotency-Key and none was sent (400).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
IdempotencyKeyReuse(message, *message_args, error_code=-1, **error_data)
¶
Bases: WebError
The idempotency key was replayed with a different request body (422).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
InvalidBatchGet(message, *message_args, error_code=-1, **error_data)
¶
Bases: WebError
A :batchGet request's ids parameter is missing or over the row cap (400).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
InvalidCursor(message, *message_args, error_code=-1, **error_data)
¶
Bases: WebError
The pagination token was absent from, or malformed in, the request (400).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
InvalidMergePatch(*message_args, **error_data)
¶
Bases: WebError
A merge-patch body is not a JSON object (422).
The message defaults to A merge patch must be a JSON object.
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
InvalidOrderBy(message, *message_args, error_code=-1, **error_data)
¶
Bases: WebError
orderBy names a field the endpoint cannot sort by, or is malformed (400).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
InvalidReadMask(message, *message_args, error_code=-1, **error_data)
¶
Bases: WebError
readMask combines * with other paths, or names an undeclared field (400).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
ItemsDenied(errors, *, root)
¶
Bases: PermissionDenied
Some items of a bulk request are not permitted (403).
Renders Forbidden with one errors entry per message, whose
pointer is /<root>/<index> (/<root>/<index>/<field> for a
field-keyed entry).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
errors
|
Mapping[str | int, Sequence[str] | Mapping[str, Sequence[str]]]
|
Messages by item index, or by item index then field name. |
required |
root
|
str
|
The first pointer segment, such as |
required |
Example::
ItemsDenied({"1": ["You may not create this order."]}, root="requests")
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
problem_extensions()
¶
Return the errors member.
MalformedPrecondition(*message_args, errors=None, **error_data)
¶
Bases: _PointedError
The precondition header was present but could not be parsed (400).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
problem_extensions()
¶
Return the errors member when one was given.
PermissionDenied(message, *message_args, error_code=-1, **error_data)
¶
Bases: WebError
Credentials verified, but the principal lacks the required access (403).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
PreconditionRequired(*message_args, errors=None, **error_data)
¶
Bases: _PointedError
The route requires a precondition and the client sent none (428).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
problem_extensions()
¶
Return the errors member when one was given.
RemoteProblem(problem, *message_args, **error_data)
¶
Bases: WebError
An upstream service returned an application/problem+json body.
Carries the parsed :class:~rn_forge.web.problem.ProblemDetail so a gateway
can re-emit the upstream's slug rather than flattening every upstream
failure into "internal error".
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problem
|
ProblemDetail
|
The parsed upstream problem. |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**error_data
|
Any
|
Forwarded to |
{}
|
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
ResourceDeleted(label, id, **error_data)
¶
Bases: DomainConflict
The resource is soft-deleted and cannot be written (409).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label
|
str
|
The resource's display name, such as |
required |
id
|
object
|
The resource identifier. |
required |
The message is {label} {id} is deleted.
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
ResourceNotDeleted(label, id, **error_data)
¶
Bases: DomainConflict
The resource is live and cannot be undeleted (409).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label
|
str
|
The resource's display name, such as |
required |
id
|
object
|
The resource identifier. |
required |
The message is {label} {id} is not deleted.
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
RowsInvalid(errors, *, root='rows')
¶
Bases: WebError
One or more rows of an import or bulk request are invalid (422).
Renders One or more rows are invalid. with one errors entry per
failed cell, whose pointer is /<root>/<row>[/<field>].
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
errors
|
Iterable[RowError]
|
The failed cells. |
required |
root
|
str
|
The first pointer segment. |
'rows'
|
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
problem_extensions()
¶
Return the errors member.
ServiceUnavailable(*message_args, retry_after=None, **error_data)
¶
Bases: WebError
The service cannot handle the request right now (503).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*message_args
|
Any
|
Forwarded to |
()
|
retry_after
|
int | None
|
Seconds the client should wait before retrying, carried
as a |
None
|
**error_data
|
Any
|
Forwarded to |
{}
|
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
response_headers()
¶
Return the Retry-After header, or nothing when unset.
SessionRequired(message, *message_args, error_code=-1, **error_data)
¶
Bases: AuthenticationFailed
A session-only route was called without a valid session (401).
The response carries no WWW-Authenticate header: a cookie session has
no registered authentication scheme to challenge with.
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
TooManyRequests(*message_args, retry_after=None, **error_data)
¶
Bases: WebError
The client has sent too many requests in a given time (429).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*message_args
|
Any
|
Forwarded to |
()
|
retry_after
|
int | None
|
Seconds the client should wait before retrying, carried
as a |
None
|
**error_data
|
Any
|
Forwarded to |
{}
|
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
response_headers()
¶
Return the Retry-After header, or nothing when unset.
UnsupportedMediaType(*message_args, **error_data)
¶
Bases: WebError
The request's media type is not one the route accepts (415).
The message defaults to Use Content-Type: application/merge-patch+json for PATCH.
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
response_headers()
¶
Return the Accept-Patch header (RFC 5789 section 2.2).
VersionConflict(*message_args, errors=None, **error_data)
¶
Bases: _PointedError
The client's precondition did not match the current version (412).
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)
problem_extensions()
¶
Return the errors member when one was given.
WebError(message, *message_args, error_code=-1, **error_data)
¶
Bases: AppException
Base class for every exception this package raises.
check(value, message, *message_args, **kwargs)
classmethod
¶
Raise this exception if value is falsy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to test. |
required |
message
|
str
|
Exception message (supports positional format args). |
required |
*message_args
|
Any
|
Forwarded to |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
Example::
AppException.check(path.exists(), "Missing file: {}", path, error_code=404)