pyjwt
PyJWT Exception Codes
Exception classes raised by PyJWT, the Python library for encoding and decoding JSON Web Tokens (JWT), used directly and as the JWT backend for many Python auth frameworks. Codes are the exception class name raised from jwt.decode() and related calls.
19 codes
· All codes 19 codes
- DecodeError DecodeError Raised when a token cannot be decoded because it failed validation — for example the token isn't valid base64url, isn't valid JSON once decoded, or doesn't have the header.payload.signature structure a JWT requires.
- ExpiredSignatureError ExpiredSignatureError Raised when a token's exp (expiration time) claim indicates that it has expired. This is one of the most common JWT failures in production and normally means the client should refresh the token or re-authenticate rather than retry the same request.
- ImmatureSignatureError ImmatureSignatureError Raised when a token's nbf (not-before) or iat (issued-at) claim represents a time in the future, so the token isn't valid yet. Often caused by clock skew between the server that issued the token and the one verifying it.
- InvalidAlgorithmError InvalidAlgorithmError Raised when the algorithm specified for signing or verification is not recognized by PyJWT, or is not included in the algorithms list passed to jwt.decode(). Also raised for the notorious 'alg: none' or algorithm-confusion attempt if it isn't explicitly allowed.
- InvalidAudienceError InvalidAudienceError Raised when a token's aud (audience) claim does not match one of the expected audience values passed to jwt.decode(). Indicates the token was issued for a different service or client than the one verifying it.
- InvalidIssuedAtError InvalidIssuedAtError Raised when a token's iat (issued-at) claim is present but non-numeric, so PyJWT cannot interpret it as a timestamp. Check whatever issued the token — it should set iat to a numeric NumericDate value (seconds since the Unix epoch).
- InvalidIssuerError InvalidIssuerError Raised when a token's iss (issuer) claim does not match the expected issuer passed to jwt.decode(). Usually means the token was issued by an authority the verifier doesn't trust for this check, or the wrong issuer string was configured.
- InvalidJTIError InvalidJTIError Raised when a token's jti (JWT ID) claim is not a string. Applications that pass a jti check to jwt.decode() to detect replay of a specific token will see this if the claim is missing its expected type.
- InvalidKeyError InvalidKeyError Raised when the key passed to jwt.encode() or jwt.decode() is not in the format the chosen algorithm expects — for example passing a raw string where a PEM-formatted RSA/EC key object is required, or a malformed PEM block.
- InvalidSignatureError InvalidSignatureError Raised when a token's signature doesn't match the one PyJWT computes from the payload and the provided key. Usually means the wrong verification key/secret was used, the token was tampered with, or it was signed with a different key than the one being checked against.
- InvalidSubjectError InvalidSubjectError Raised when a token's sub (subject) claim is not a string, or doesn't match the expected subject value passed to jwt.decode(). Indicates the token identifies a different principal than the one the caller expected.
- InvalidTokenError InvalidTokenError Base exception raised when jwt.decode() fails on a token. Most of PyJWT's specific validation errors (expired, wrong audience, wrong issuer, and so on) subclass this, so catching InvalidTokenError is a common way to treat any invalid-token condition as a single failure case.
- MissingCryptographyError MissingCryptographyError Raised when the chosen algorithm (such as RS256 or ES256) requires the optional cryptography package and it isn't installed. Fix by installing PyJWT with the crypto extra, e.g. pip install 'pyjwt[crypto]'.
- MissingRequiredClaimError MissingRequiredClaimError Raised when a claim listed in the require option passed to jwt.decode() is not present in the token's claim set. Used to enforce that claims like exp or aud are mandatory rather than merely validated when present.
- PyJWKClientConnectionError PyJWKClientConnectionError Raised by PyJWKClient when it fails to fetch the JWK Set from the configured JWKS URL over the network — for example the endpoint is unreachable, times out, or returns a non-2xx response.
- PyJWKClientError PyJWKClientError Raised by PyJWKClient when it cannot resolve the signing key for a token from a remote JWKS endpoint — for example the token's kid (key ID) header doesn't match any key in the fetched JWK set.
- PyJWKError PyJWKError Base class for errors related to JSON Web Keys (JWKs) in PyJWT, such as constructing a PyJWK from key data. More specific JWK-related failures — client errors, set errors, and missing dependencies — subclass this.
- PyJWKSetError PyJWKSetError Raised when a JWK Set (a JSON document listing multiple JWKs, typically fetched from a JWKS endpoint) cannot be parsed or contains no usable keys — for example malformed JSON or an empty 'keys' array.
- PyJWTError PyJWTError Base class for every exception PyJWT raises. Catching PyJWTError catches any failure from the library, including decode failures and JWK-related errors; catch a more specific subclass when you need to distinguish the cause.