Error recovery

Most auth4.dev errors have one safe recovery: start the step again. This page lists the errors your code can see and what to do about each.

Principles

Don't retry single-use steps automatically. Authorization codes, state, proofs and device codes work once. Start a fresh flow instead.
Retry only transient failures (network errors, temporarily_unavailableand 5xx responses), with backoff.
Keep the player's state when a failure is transient. Sign the player out only when auth4.dev says the session is gone (invalid_grant on refresh).
Show short, honest messages and never show raw tokens or response bodies.

Token, device and revocation endpoints return standard OAuth errors:

{ "error": "invalid_grant", "error_description": "…" }

Error	Meaning	Recovery
`invalid_request`	Missing, duplicate or malformed parameter.	Fix the request. Don't retry unchanged.
`invalid_client`, `unauthorized_client`	Unknown or disabled application, or a grant its type doesn't allow.	Check the client ID, application type and that the application is enabled.
`invalid_grant`	Code, refresh token or device code is expired, used, revoked or doesn't match.	Start sign-in again. For refresh, clear the session.
`invalid_scope`	A requested scope isn't allowed for this application.	Request fewer scopes, or allow them in the console.
`unsupported_grant_type`	Implicit, password or another unsupported grant.	Use authorization code with PKCE, or device authorization.
`access_denied`	The player cancelled, declined consent or denied a device.	Return to your start screen. Offer to try again.
`authorization_pending`, `slow_down`	Device approval isn't finished, or you polled too soon.	Keep polling at the interval; add 5 seconds after `slow_down`.
`expired_token`	The device code expired.	Start a new device authorization.
`temporarily_unavailable`, 5xx	auth4.dev or a provider is briefly unavailable.	Retry with backoff.

Error	Meaning	Recovery
`invalid_code`	Wrong, expired or used email code, too many guesses, or an unknown address while sign-up is off. These cases look the same on purpose.	Let the player retype the code or request a new one.
Rate limited (`slow_down`)	Too many codes sent or guessed.	Ask the player to wait before trying again.
`409 identity_in_use`	The email or Discord account belongs to another player.	The guest is unchanged. Offer the choices in Guest accounts.
Expired sign-in link	The hosted login flow lasts ten minutes.	Hosted login shows this. Your app starts sign-in again.

Management responses use one error shape. Quote the request_id when asking for help.

{ "error": { "code": "invalid_redirect_uri", "message": "…", "request_id": "…", "details": {} } }

Code	Meaning
`forbidden`	You aren't a member of this project, or it doesn't exist.
`insufficient_role`	Your role can't make this change. Ask an owner.
`project_suspended`	The project is suspended and its configuration can't change.
`invalid_redirect_uri`, `invalid_origin`	Not HTTPS or loopback, includes credentials, a fragment or a wildcard, or uses an auth4.dev origin.
`invalid_scope`	Reserved scope, or outside the project's allowed scopes.
`scope_in_use`	An application still uses the scope you're removing from the project.
`temporarily_unavailable`	Nothing was saved. Try again.