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)