Error Reference

Every error AgeWallet returns, grouped by where it surfaces. If you are writing callback logic rather than looking something up, start with Handling responses and errors — this page is a lookup.

Errors returned to your redirect_uri

The authorization flow started, and ended without a code. The user’s browser comes back to your callback with an error parameter instead of code.

Error	Cause	Category	Action
access_denied	The user cancelled verification.	Flow outcome	Deny access. Offer to start again.
access_denied	Identity verification was unsuccessful — document rejected, liveness check failed, or session expired.	Flow outcome	Deny access. You may offer a retry.
invalid_request	code_challenge_method was not S256.	Request fault	Fix your /authorize request. This should never reach production.

Errors from the token endpoint

Returned by POST /user/token as HTTP 400 with a JSON body containing an error field (invalid_client is returned as HTTP 401). These are request faults: the user is not involved.

Error	Usual cause
invalid_grant	The code expired; the code was already used; redirect_uri does not match the /authorize request; or code_verifier does not match the challenge you sent.
invalid_client	Unknown client_id, or a missing or incorrect client_secret.
invalid_request	redirect_uri or code_verifier is missing.
unsupported_grant_type	grant_type is not authorization_code — including when the body is sent as JSON rather than form-encoded, which makes all parameters unreadable.

Errors from UserInfo

Returned by GET /user/userinfo.

Status	Meaning	Action
401	The access token is missing, expired, or invalid.	Do not treat this as an unverified user. It is an integration fault.
5xx	Service error.	Do not grant access. Retry once, then fail closed.

A failed request and a failed verification both end in “no access”, but only one of them is a bug in your integration. Log them separately.

Errors you will not receive

Some failures cannot be sent to your callback, because doing so would mean redirecting to a URI we have not been able to verify. In these cases the user sees an error page and your callback is never reached:

• redirect_uri is missing, malformed, or does not exactly match one registered for the client
• client_id is unknown

If your callback never fires and the user reports an error screen, check these two first.