Troubleshooting
What the usual sign-in and API errors mean, and what to change.
Each entry is something the issuer or an API answers, and what usually causes it. Every API error code has its own page under Errors.
The sign-in page says the redirect URI isn't registered
The authorization request's redirect_uri must match one of the app's registered redirect URIs exactly: scheme, host, port, path and trailing slash. Synq doesn't match prefixes or wildcards. Add the exact URI to the app, or send the one it has.
invalid_request: PKCE is required
Every public app sends PKCE (code_challenge with S256), and so does a confidential app unless its tenant turned it off for that app. Send a fresh code_verifier with each sign-in, and its S256 hash as the challenge. @synqauth/js does this for you.
invalid_grant when redeeming a code
A code works once, for a minute, with the same redirect_uri and the code_verifier that matches its challenge. A second redemption, a late one or a different verifier is refused. Start the sign-in again.
invalid_grant when refreshing, and the person is signed out
Refresh tokens rotate on every use. Presenting one that was already used ends the whole grant, new tokens included, because that is what a stolen token looks like. Refresh once at a time per session: @synqauth/js and @synqauth/nextjs hold a lock so concurrent requests share one refresh. Clients that share a store need one with a lock.
An API refuses a token with invalid_token
Check that the token was asked for that API (resource=<the API's identifier>), so its aud is that identifier; that the API checks the right issuer; and that the token hasn't expired (5 to 15 minutes). A token without a resource is for userinfo alone.
insufficient_scope or insufficient_permissions
insufficient_scope: the access token lacks a scope the route needs. Ask for it in the sign-in's scope, and make sure the app may ask for it (…/apps/{app}/apis/{api}). insufficient_permissions: the management API credential's role or key lacks the permission named in missing_permission. See Permissions.
fresh_sign_in_required
The route wants the person to have signed in recently, and their sign-in is older than it allows, or Synq never saw when it happened (some providers don't say). Send them to sign in again with prompt=login.
Adding a way to sign in fails with email_unverified or sign_in_method_unavailable
email_unverified: the account signs in with an address nobody proved yet; it takes no new way in until the person verifies it. sign_in_method_unavailable: the brand doesn't offer that method, or it can't show a fresh sign-in. See Linking.
429 with Retry-After
A rate limit. Wait the seconds Retry-After gives, then try once more. See Rate limits for each rule.