Errors¶
When something goes wrong, who throws an exception. Who answers it depends on where the request went:
- Under who's base path (
who.base-path,/whoby default: every who endpoint, Spring Security's sign-in filters included), who answers it itself, with RFC 9457 Problem Details, whatever your application's own error handling says. who's TypeScript client reads one shape. - Anywhere else (your own endpoints, guarded by who's chains), your application answers who's exception the same way it answers its own errors, for example from a
@RestControllerAdvice. See Your own endpoints.
Either way, the Who-Error header names the failure.
who's answer¶
HTTP/1.1 404 Not Found
Content-Type: application/problem+json
Who-Error: session-not-found
{"type": "urn:who:error:session-not-found", "title": "Not Found", "status": 404,
"detail": "No session of yours has that id", "code": "session-not-found"}
| Member | Value |
|---|---|
type |
urn:who:error: and the code |
title |
the status's reason phrase |
status |
the HTTP status |
detail |
the exception's message, for a person; null for a 5xx, whose message may carry what a client must not see |
code |
the same code as the Who-Error header |
Every error under the base path has a code: who's exceptions their own (the tables below), and anything else one named from its status (400 invalid-request, 401 unauthorized, 403 forbidden, 404 not-found, 405 method-not-allowed, 406 not-acceptable, 415 unsupported-media-type, any 5xx server-error, any other status error). Spring Security's CSRF refusal is 403 invalid-csrf-token, so a client knows to fetch a new token and retry. A 5xx is logged at ERROR with its stack trace.
The members keep these names and an instant stays a string whatever spring.jackson says: who's answers pin their JSON shape on their own types.
The exceptions¶
| Exception | Status | When |
|---|---|---|
SignInFailedException |
401 | A sign-in failed: a bad, expired or used email-link token; an unknown or invalid passkey; an inactive identity. Its message is always "Sign-in failed", so the reason never reaches a response. The cause keeps it for your logs. |
NotSignedInException |
401 | A request needs a signed-in caller and has none: a protected URL, GET /who/me, any endpoint under /who/me, or an admin endpoint. |
ReauthenticationRequiredException |
401 | A browser session signed in more than who.security.recent-sign-in ago tried something that needs a recent sign-in: adding or removing a credential (a passkey, a provider account, an email address), ending another session, making or rotating an API key, changing an identity through the admin endpoints, or an action marked @RequiresRecentSignIn. Sign the user in again, then retry. |
InsufficientUserAuthenticationException |
401 | A JWT whose auth_time is too old called an action marked @RequiresRecentSignIn. A 401 answer carries WWW-Authenticate: Bearer error="insufficient_user_authentication", …, max_age=<seconds> (RFC 9470), whether who, your advice or Spring MVC writes it; any other answer carries none. An answer that sets its own Bearer challenge (a realm, a scope) keeps it; one challenging with another scheme gets who's beside it. The client signs the person in again and retries. The challenge is also on the exception, challenge(). |
RecentSignInUnavailableException |
403 | An API key, or a JWT without an auth_time claim, called an action marked @RequiresRecentSignIn. Neither can ever be recent, so it is a 403, not a challenge. It is an AccessDeniedException. |
InvalidPasskeyRegistrationException |
400 | A passkey registration failed verification. It carries no cause, because WebAuthn details must not travel. |
SessionNotFoundException |
404 | DELETE /who/me/sessions/{id} named a session that is not one of the caller's. |
BrowserSessionRequiredException |
403 | An endpoint that needs a browser session on its own was called by something else: a bearer token or an API key at a /who/me endpoint only a browser may call, a session cookie with an API key or a bearer token beside it at any endpoint that tells the two apart (the /who/me endpoints, POST /who/me/api-keys and its kin, and an admin change), or a sign-in no browser session loaded. Send the cookie alone. It is an AccessDeniedException. |
AccessDeniedException (Spring Security's own) |
403 | A signed-in caller lacks a permission. Spring Security 7 raises its subclass AuthorizationDeniedException. |
Managing passkeys adds one, from who-passkey:
| Exception | Status | When |
|---|---|---|
PasskeyNotFoundException |
404 | DELETE /who/me/passkeys/{credentialId} named a passkey that is not one of the caller's. |
Removing a passkey, an email address or a linked account through /who/me adds one, from who-core:
| Exception | Status | When |
|---|---|---|
LastCredentialException |
409 | The removal would leave the identity with no way to sign in. API keys do not count. |
Provider sign-in adds these, for its confirm endpoints:
| Exception | Status | When |
|---|---|---|
HumanCheckFailedException |
403 | The application's human check refused a request to /who/email/send or /who/email/sign-in, or could not decide it. It is an AccessDeniedException. |
SignUpRefusedException |
403 | POST /who/oidc/pending/sign-up refused by the sign-up policy, or sent by a browser that is signed in. |
UnknownProviderException |
404 | POST /who/me/accounts/{registrationId} named a registration who does not sign in with. |
PendingSignUpNotFoundException |
404 | No pending sign-up, or an expired or used one, at GET /who/oidc/pending, POST /who/oidc/pending/sign-up or POST /who/oidc/pending/link. |
AlreadyLinkedException |
409 | POST /who/oidc/pending/link for an account linked to another identity. |
LinkedAccountNotFoundException |
404 | DELETE /who/me/accounts/{id} named an account that is not one of the caller's: unknown, malformed or another identity's. |
POST /who/oidc/pending/link and POST /who/me/accounts/{registrationId}, which starts a link, also answer NotSignedInException and ReauthenticationRequiredException.
Managing email addresses adds three, besides NotSignedInException and ReauthenticationRequiredException:
| Exception | Status | When |
|---|---|---|
EmailCredentialNotFoundException |
404 | POST /who/me/email-addresses named a replaces, or DELETE /who/me/email-addresses/{id} an id, that is not one of the caller's email addresses. |
InvalidEmailAddressConfirmationException |
400 | POST /who/me/email-addresses/confirmations matched nothing: no request by this identity, an expired or used one, a wrong code, a code with no attempts left, or neither or both of token and code. |
EmailAddressTakenException |
409 | The confirmed address was registered to someone in the meantime, or POST /who/invitations named an address that is already an identity's. EmailCredentialService.register and InvitationService.invite throw it too. |
Managing API keys adds three:
| Exception | Status | When |
|---|---|---|
ApiKeyNotFoundException |
404 | POST /who/me/api-keys/{id}/rotations or DELETE /who/me/api-keys/{id} named a key that is not one of the caller's (unknown, malformed or another identity's), or GET /who/me/api-keys/current came from a request no API key signed in. |
ApiKeyCannotManageKeysException |
403 | A request an API key signed in called an API-key endpoint other than GET /who/me/api-keys/current: a key never lists, makes, rotates or revokes keys. It is an AccessDeniedException, and its own code rather than browser-session-required, because a bearer token may manage keys too. |
InvalidApiKeyRequestException |
400 | POST /who/me/api-keys or a rotation that who refuses as it stands: a body that is not the expected JSON, a lifetime or overlap that is not an ISO-8601 duration or is out of range, a blank name, no scopes or a scope the owner does not hold, or a key that expired or was revoked before its rotation. |
The admin endpoints add eight, and invitations one more:
| Exception | Status | When |
|---|---|---|
PermissionRequiredException |
403 | The caller's permissions lack who.identities.read or who.identities.manage, whichever the endpoint needs. For an API key, its scopes decide. The message names the permission. |
RoleGrantForbiddenException |
403 | PUT /who/identities/{id}/roles/{role} or POST /who/invitations would grant a role carrying a permission the caller does not hold itself. |
IdentityNotFoundException |
404 | The path names no identity: unknown, or not a UUID. |
UnknownRoleException |
404 | PUT or DELETE /who/identities/{id}/roles/{role} named a role that does not exist. |
InvalidAdminRequestException |
400 | A page or size out of range, a status who does not take, a body that is not the expected JSON, or a search by email= without email sign-in. The message names the rule broken. |
SelfDeactivationException |
409 | PATCH /who/identities/{id} with DISABLED named the caller's own identity. |
IdentityOutranksCallerException |
403 | A change to another identity that holds a permission the caller does not. |
LastAdminException |
409 | A deactivation or role removal would leave no active identity holding who.identities.manage. |
InvalidInvitationException |
400 | POST /who/invitations, or InvitationService.invite, with a missing or malformed address, a blank role name or one naming no role, or roles in an application without who-rbac. |
All of them are in org.jwcarman.who.spring.security.web, except Spring's AccessDeniedException, LastCredentialException (org.jwcarman.who.core.exception), PasskeyNotFoundException (org.jwcarman.who.passkey), the provider exceptions (org.jwcarman.who.oidc), the email address and invitation exceptions (org.jwcarman.who.emaillink), the API key exceptions (org.jwcarman.who.apikey) and the admin exceptions (org.jwcarman.who.admin).
The Who-Error header¶
Every failure under who's base path names itself in a Who-Error response header, the same code as the body's code. Outside it, every failure in the tables above, except Spring's own AccessDeniedException, does too, whatever body your application writes. A client can tell failures apart by it without knowing your body's shape; who's TypeScript client reads the header first and falls back to the body's code.
Who-Error |
Exception |
|---|---|
not-signed-in |
NotSignedInException |
reauthentication-required |
ReauthenticationRequiredException |
sign-in-failed |
SignInFailedException |
insufficient-user-authentication |
InsufficientUserAuthenticationException |
recent-sign-in-unavailable |
RecentSignInUnavailableException |
invalid-passkey-registration |
InvalidPasskeyRegistrationException |
session-not-found |
SessionNotFoundException |
passkey-not-found |
PasskeyNotFoundException |
invalid-confirmation |
InvalidEmailAddressConfirmationException |
email-address-not-found |
EmailCredentialNotFoundException |
email-address-taken |
EmailAddressTakenException |
no-pending-sign-up |
PendingSignUpNotFoundException |
human-check-failed |
HumanCheckFailedException |
sign-up-refused |
SignUpRefusedException |
unknown-provider |
UnknownProviderException |
already-linked |
AlreadyLinkedException |
linked-account-not-found |
LinkedAccountNotFoundException |
browser-session-required |
SessionNotFoundException |
BrowserSessionRequiredException |
|
api-key-cannot-manage-keys |
ApiKeyCannotManageKeysException |
last-credential |
LastCredentialException |
api-key-not-found |
ApiKeyNotFoundException |
permission-required |
PermissionRequiredException |
role-grant-forbidden |
RoleGrantForbiddenException |
identity-outranks-caller |
IdentityOutranksCallerException |
identity-not-found |
IdentityNotFoundException |
unknown-role |
UnknownRoleException |
self-deactivation |
SelfDeactivationException |
last-admin |
LastAdminException |
invalid-request |
InvalidAdminRequestException, InvalidApiKeyRequestException, InvalidInvitationException; under who's base path, any other 400 |
invalid-csrf-token |
Spring Security's CSRF refusal, under who's base path |
unauthorized, forbidden, not-found, method-not-allowed, not-acceptable, unsupported-media-type, server-error, error |
under who's base path, an error no who exception names, by its status |
The codes are a public contract and do not change between releases. Each exception returns its code from errorCode(): the WhoErrorCode interface, or, for LastCredentialException, which lives in who-core without Spring, a method of its own.
Outside the base path, who sets the header before handing the exception to your application, so your advice's body and the header arrive together. An advice that calls response.reset() clears it. A page on another origin can read it only if your CORS configuration lists it in Access-Control-Expose-Headers.
Your own endpoints¶
Outside who's base path, who's exceptions are yours to answer: NotSignedInException from who's entry point when a signed-out caller reaches a protected URL, ReauthenticationRequiredException from @RequiresRecentSignIn, AccessDeniedException from your own rules.
Many of these happen inside Spring Security's filters, before Spring MVC runs, and an exception thrown there never reaches a @RestControllerAdvice. who therefore hands each one to your application's Spring MVC exception resolvers, the handlerExceptionResolver bean, through WhoExceptionHandoff. A controller exception travels the same path, so one advice covers both. This needs Spring MVC, which every Spring Boot servlet application has.
The advice must be global: one limited by basePackages, assignableTypes or annotations never sees who's errors from filters, because they are not raised by a controller. Your advice never sees an error under who's base path: who's WhoErrorResolver runs first among Spring MVC's resolvers and answers those itself.
When nothing in your application handles an exception, who calls response.sendError(status) with the status in the table, and Spring Boot forwards the request to its error page, /error. When that status is a 5xx, who first logs the exception at ERROR with its stack trace. What the client receives then depends on your chain. If /error needs a signed-in caller, as it does under anyRequest().authenticated(), a signed-out client gets the bare status with an empty body. Permit it (requestMatchers("/error").permitAll()) to get Spring Boot's default error body instead.
who's autoconfiguration connects the handoff to your exception resolvers and puts WhoErrorResolver first. An application that builds who's beans itself, without the autoconfiguration, gets a handoff with no resolver: it only calls sendError, and your advice never sees who's errors. Build one with new WhoExceptionHandoff(paths, (request, response, e) -> resolver.resolveException(request, response, null, e) != null) over your handlerExceptionResolver bean.
Example: Problem Details for your own endpoints¶
@RestControllerAdvice
class WhoProblems {
@ExceptionHandler(SignInFailedException.class)
ProblemDetail signInFailed() {
return ProblemDetail.forStatusAndDetail(HttpStatus.UNAUTHORIZED, "Sign-in failed");
}
@ExceptionHandler(NotSignedInException.class)
ProblemDetail notSignedIn() {
return ProblemDetail.forStatusAndDetail(HttpStatus.UNAUTHORIZED, "Sign in to continue");
}
@ExceptionHandler(ReauthenticationRequiredException.class)
ProblemDetail reauthenticate() {
return ProblemDetail.forStatusAndDetail(
HttpStatus.UNAUTHORIZED, "Sign in again to register a passkey");
}
@ExceptionHandler(InvalidPasskeyRegistrationException.class)
ProblemDetail invalidRegistration() {
return ProblemDetail.forStatusAndDetail(
HttpStatus.BAD_REQUEST, "The passkey could not be registered");
}
@ExceptionHandler(AccessDeniedException.class)
ProblemDetail denied() {
// a signed-out caller can reach a method-security check when the URL rules let it through
Authentication caller = SecurityContextHolder.getContext().getAuthentication();
if (caller == null || caller instanceof AnonymousAuthenticationToken) {
return ProblemDetail.forStatusAndDetail(HttpStatus.UNAUTHORIZED, "Sign in to continue");
}
return ProblemDetail.forStatusAndDetail(HttpStatus.FORBIDDEN, "You do not have permission");
}
}
Give each one a type URI if your clients tell problems apart by type. Don't put the exception's cause in the response.