OAuth error handling
Authorization callback
Sigma can redirect with error and error_description instead of a code. Validate the browser-bound state transaction and issuer before displaying an error or acting on a callback. Reject duplicate query parameters. Escape descriptions as text and avoid including raw query strings in telemetry.
| Error/category | Action |
|---|---|
access_denied | Explain that sign-in was cancelled; allow a fresh attempt |
invalid_request | Check required parameters, scopes, PKCE, and exact redirect URI |
invalid_client | Check client registration and server member-key configuration |
invalid_grant | Treat the code/refresh credential as rejected; restart sign-in when appropriate |
| 429 | Honor Retry-After and avoid concurrent retries |
| 5xx/network failure | Show a recoverable error; do not assume a timed-out mutation failed before committing |
Error codes depend on the endpoint and Better Auth version. This is a handling guide, not an exhaustive promise of every response code.
Client signature failures
For the token endpoint, confirm client_id is registered, accountPubkey is configured, and the member WIF derives that exact public key. Sign /api/auth/oauth2/token with the same form-encoded body that is sent. A missing X-Auth-Token is not fixed by adding a generic client secret or removing PKCE.
Local callback failures
createCallbackHandler() does not create a local session. If userinfo succeeds but your app remains signed out, inspect the local session adapter and Set-Cookie handling. Explicitly configure the app origin behind a reverse proxy. Never disable state checks or trust arbitrary forwarded hosts to make a redirect error disappear.
For the browser plugin, parseErrorParams() from /next reads URL error fields; it does not validate the OAuth transaction. handleCallback() consumes browser state, so repeated execution can fail even when the first exchange succeeded.
API error formats
OAuth protocol paths use OAuth-style error/error_description. Custom APIs can return RFC 9457 problem JSON or feature-specific envelopes. Check HTTP status and content type before interpreting the body. See API errors for a tolerant response parser and diagnostic checklist.