Skip to content

xtr_security_oauth2_server_core.exception

The errors this library raises, one family under one base.

Every error derives from :class:OAuth2Error, so one except OAuth2Error catches anything this library raises. The bundle that wires this library into an application adds its own errors beside these, each deriving from the same base.

  • :class:OAuth2Error — the base of them all.
  • :class:InvalidArgumentError — one of this library's own objects used wrongly, which is a caller's mistake and nobody's answer.
  • :class:OAuthServerError — a refusal the protocol has a name for, and the answer that carries it.
  • :class:UniqueTokenIdentifierConstraintViolationError — a token identifier that was already taken, which a grant retries past.

InvalidArgumentError

Bases: OAuth2Error, ValueError

A call into this library was malformed, and no client caused it.

An access token asked for its string form before it was handed a signer, an extra claim taking a name the token mints itself, an authorization request read before the server had understood it, an encryption key that is not a key — mistakes caught where they are made.

Deliberately not an OAuthServerError: that one is the answer a client gets, and there is no answer to give here, because nothing a client sent caused it. Whoever catches one has a wiring or an ordering mistake to fix, so it derives from :class:OAuth2Error — one except OAuth2Error still catches everything this library raises — and from nothing of the security family, which only answers failed authentication.

Also a :class:ValueError, so code guarding a call with except ValueError keeps working, the same reason the security family's error of this name is one.

OAuth2Error

Bases: Exception

Base class for every error raised by this library.

Catch this to handle anything the authorization server, the resource server or their wiring can go wrong with; catch a subclass to handle one cause. Every subclass carries the data a caller needs as typed attributes and composes its own message from them.

It derives from :class:Exception rather than from the security family's base, because most of what this library raises is a protocol answer — a request naming an unknown grant, a code that was already redeemed — not a failure of the family's authentication machinery. The errors the firewall will have to answer will be the exception: they will mix the family's AuthenticationError in beside this base, so one except SecurityError will still catch those while one except OAuth2Error catches everything from here.

OAuthServerError

OAuthServerError(message: str, code: int, error_type: str, http_status_code: int = 400, hint: str | None = None, redirect_uri: str | None = None)

Bases: OAuth2Error

A refusal the protocol has a name for, carrying everything needed to answer it.

Raised wherever a request cannot be honoured: an unknown grant type, a client that failed authentication, a code that was already redeemed. The error is not only a message — it is the answer, so whoever catches it asks for one with :meth:generate_http_response and sends it.

Raise it through one of the named constructors, never by naming a number: each one fixes the error name the protocol uses, the status the answer carries and the number the error is catalogued under, and that triple is the contract a client reads. Chain the cause the usual way — raise OAuthServerError.invalid_refresh_token() from cause — so the traceback keeps what actually went wrong without the answer naming it.

An error carrying a redirect URI is answered as a redirect rather than as a document: an authorization request that named a redirect gets its refusal delivered there, because that is where the client is waiting.

Record one answer: what went wrong, what to call it, and how to send it.

message and error_type become the error_description and the error of the payload, and code is the number the error is catalogued under — stable across versions, so a caller may switch on it. A hint is sent when there is one, and an empty string counts as one: only None leaves the field out. A redirect_uri is where the refusal is to be delivered, when the request named anywhere.

unsupported_grant_type classmethod

unsupported_grant_type() -> Self

The request named a grant this server does not run.

invalid_request classmethod

invalid_request(parameter: str, hint: str | None = None) -> Self

A parameter is missing, repeated or unusable.

Names parameter in the hint unless the caller has something more useful to say about it.

invalid_client classmethod

invalid_client(server_request: ServerRequestInterface) -> Self

The client could not be authenticated.

Takes the request because the answer depends on how the client tried: one that sent an Authorization header is told which scheme to try again with. The message says no more than that authentication failed — which client, and why, is never told to the caller.

invalid_scope classmethod

invalid_scope(scope: str, redirect_uri: str | None = None) -> Self

The request asked for a scope this server does not know.

The scope is repeated back in the hint, escaped: it came from the request, and an application may well render the hint in a page.

invalid_credentials classmethod

invalid_credentials() -> Self

The user's own credentials were wrong.

server_error classmethod

server_error(hint: str) -> Self

Something broke that the request could have done nothing about.

The reason goes into the description rather than the hint, because there is nothing the client can change about it.

invalid_refresh_token classmethod

invalid_refresh_token() -> Self

The refresh token could not be read, or is no longer usable.

One answer for every reason — unreadable, another client's, expired, revoked, already spent — so a client learns nothing about a token it should not hold; the reason stays in the server's traceback.

access_denied classmethod

access_denied(hint: str | None = None, redirect_uri: str | None = None) -> Self

The user, or the server itself, refused the request.

invalid_grant classmethod

invalid_grant() -> Self

The grant presented is not one this client can redeem now.

The catch-all for a code or refresh token that is unknown, expired, revoked, bound to another redirect URI or issued to another client — deliberately one answer for all of them, with no hint, so a client cannot tell which.

expired_token classmethod

expired_token(hint: str | None = None) -> Self

The device code polled for has expired and its session is over.

authorization_pending classmethod

authorization_pending(hint: str = '') -> Self

The user has not finished approving the device yet; keep polling.

slow_down classmethod

slow_down(hint: str = '') -> Self

The device polled too soon; it must wait five seconds longer from now on.

unauthorized_client classmethod

unauthorized_client(hint: str | None = None) -> Self

The client authenticated, but is not allowed this grant.

unsupported_token_type classmethod

unsupported_token_type(hint: str | None = None) -> Self

The client named a kind of token this server cannot act on.

This server issues two kinds of token — access tokens and refresh tokens — and withdraws either. A token read as a third kind, which only a deployment that reads tokens of its own can produce, is refused rather than answered as though it had been withdrawn (RFC 7009, Section 2.2.1).

get_code

get_code() -> int

Return the number this error is catalogued under.

get_error_type

get_error_type() -> str

Return the error name the answer carries as error.

get_http_status_code

get_http_status_code() -> int

Return the status a document answer carries.

It is never 302, even for an error that redirects: the status of the refusal and the fact that it is delivered by redirect are two different things, so an application overriding error pages can let the redirects through — see :meth:has_redirect.

get_hint

get_hint() -> str | None

Return what the client could change, or None when there is nothing.

has_redirect

has_redirect() -> bool

Tell whether this refusal is to be delivered to a redirect URI.

get_redirect_uri

get_redirect_uri() -> str | None

Return where the refusal is to be delivered, if anywhere.

carry_issuer

carry_issuer(issuer: str) -> None

Have a redirected refusal name issuer as iss, as every redirect does.

RFC 9207 puts the issuer on refusals as on successes, so a client talking to several servers can tell which one sent the browser back. A refusal a grant built already names it and is left as it is; one answered as a document goes to no redirect and carries nothing.

get_payload

get_payload() -> Mapping[str, str]

Return what the answer says, as a read-only view.

error and error_description always, hint when there is one. Use :meth:set_payload to change it; the view answers the payload as it stood when it was asked for.

set_payload

set_payload(payload: Mapping[str, str]) -> None

Replace what the answer says.

For a caller that has to shape the answer itself — adding a field an extension defines, or dropping the hint from a public error.

set_server_request

set_server_request(server_request: ServerRequestInterface) -> None

Record the request this refusal answers.

Only the client-authentication answer reads it, to name back the scheme the client tried.

get_http_headers

get_http_headers() -> Mapping[str, str]

Return the headers a document answer carries, their names lowercased.

A client that tried to authenticate with an Authorization header and failed is told which scheme to try again with: RFC 6749 §5.2 has the 401 answering such a request carry WWW-Authenticate for the scheme the client used. A client that put its credentials in the form instead attempted no scheme, so none is named — and a header handed on empty, as some servers do when the client sent none, counts as no attempt either.

generate_http_response async

generate_http_response(response: ResponseInterface, use_fragment: bool = False) -> ResponseInterface

Build the answer to this error on top of response.

With a redirect URI, the answer is a 302 whose Location carries the payload — in the query, or in the fragment when use_fragment is set, as a refusal to an implicit-grant request needs. Nothing else is added to it: a browser is going to follow the redirect, and a content type would only describe a body that is not there.

Without a redirect URI, the answer is the payload as a JSON document, carrying this error's status and headers.

Asking twice answers the same thing: the error is left as it was, so the redirect target does not grow a separator each time.

UniqueTokenIdentifierConstraintViolationError

UniqueTokenIdentifierConstraintViolationError(message: str, code: int, error_type: str, http_status_code: int = 400, hint: str | None = None, redirect_uri: str | None = None)

Bases: OAuthServerError

Storing a token failed because its identifier was already in use.

A repository raises this when the identifier a grant generated collides with one already stored. It is the one error of this library that is normally never answered: a grant catches it and mints a new identifier, and only a run of collisions long enough to exhaust its retries lets it out — which is why it is a 500 rather than a refusal the client could do anything about.

create classmethod

create() -> Self

Report that no free identifier could be found.