Exceptions

RoundlyConsulting\Jwt\Jose\Exceptions\JwtException extends RuntimeException and is the base of every token error. Catch it to handle any failure uniformly, or a subclass for a precise cause:

use RoundlyConsulting\Jwt\Facades\Jwt;
use RoundlyConsulting\Jwt\Jose\Exceptions\JwtException;
use RoundlyConsulting\Jwt\Jose\Exceptions\TokenExpired;

try {
    $claims = Jwt::verify($jwt);
} catch (TokenExpired $e) {
    // Prompt a re-login / refresh flow.
} catch (JwtException $e) {
    // Any other token failure: 401.
}

Misconfiguration is a 500, not a 401

Both guards turn a JwtException into a null user — a 401. Operator errors must never take that path, so they are deliberately not JwtExceptions:

• RoundlyConsulting\Jwt\Exceptions\JwtMisconfigured — an issuer or audience that is not set (null or blank), a guard name that isn’t a jwt guard, an uncallable token_version, a guard mintAccessToken() whose request names another audience, or a config value of the wrong shape — a TTL of five, an unparseable switch, a malformed service.secrets pair or an issuer it names twice, an identity that isn’t a ClaimsAuthenticatable. It never prints a secret: a repeated issuer is named only when it looks like one, otherwise by the entries’ positions, and for service.secret / service.secrets the message gives only the value’s type (“must be a string or null, array given”), while the value never rides a trace frame.
• RoundlyConsulting\Jwt\ServiceTokens\Exceptions\ServiceAuthMisconfigured — a missing or weak service secret, no resolvable service name, no audience or own issuer on issue, a missing own entry in the per-issuer map, or reserved extra claims.
• KeyLoadFailed is a JwtException, but the jwt guard rethrows it ahead of the generic handler — a missing or invalid RSA key is an operator error, not an unauthenticated caller.

KeyLoadFailed messages are actionable: they name the missing or unreadable path and the fix, such as running jwt:generate-keys, setting the env var or granting the PHP user read access.