Skip to content

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 "requests" or "ids".

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 AppException.

()
**error_data Any

Forwarded to AppException.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 Note.

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 Note.

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 AppException.

()
retry_after int | None

Seconds the client should wait before retrying, carried as a Retry-After response header. None sends no header.

None
**error_data Any

Forwarded to AppException.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 AppException.

()
retry_after int | None

Seconds the client should wait before retrying, carried as a Retry-After response header. None sends no header.

None
**error_data Any

Forwarded to AppException.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

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 message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

Example::

AppException.check(path.exists(), "Missing file: {}", path, error_code=404)