Error code index · IntelliAuth Docs

This is the catalogue. Codes are grouped by family; within each row you get the meaning, the recommended user-facing copy (translate / brand as needed), the right programmatic response, and a link to the dedicated troubleshooting topic where one exists.

The codes are stable. Messages may improve between releases; match on code, not on message text.

Authentication

Code	User-facing copy	Programmatic
`invalid_credentials`	"The email or password is incorrect."	Show form error, allow retry
`account_disabled`	"This account has been disabled. Contact your administrator."	Stop sign-in; offer contact
`account_locked`	"Too many failed attempts. Try again in a few minutes."	Surface `details.retry_after_s`
`email_unverified`	"Verify your email before signing in. Check your inbox for a link."	Offer "resend verification"
`password_must_be_reset`	"Set a new password to continue."	Redirect to reset flow
`mfa_required`	(don't show — render MFA UI)	See Handling mfa_required
`mfa_enrolment_required`	"We need to set up MFA before you can sign in."	Render enrolment UI
`step_up_required`	(don't show — start step-up)	See Step-up
`captcha_required`	(don't show — render captcha)	See captcha_required

OAuth flow

Code	User-facing copy	Programmatic
`invalid_redirect_uri`	"Sign-in configuration error. Contact support."	Don't retry — config issue. Topic
`invalid_client`	"Sign-in configuration error. Contact support."	Don't retry — client_id or secret wrong
`invalid_grant`	(varies)	The grant didn't match; usually means refresh_token expired or revoked
`invalid_scope`	"Permission requested isn't allowed for this app."	Drop the bad scope; retry
`unauthorized_client`	"Sign-in configuration error. Contact support."	Client not allowed to use this grant
`consent_required`	"Approve the requested permissions to continue."	Redirect through interactive auth
`state_mismatch`	"Sign-in security check failed. Start from the home page."	CSRF defence — don't silent-retry. Show a clear restart path.
`pkce_required`	"Sign-in configuration error. Contact support."	Client missed code_challenge

Session

Code	User-facing copy	Programmatic
`token_expired`	(don't show — auto-refresh)	The access token's `exp` passed. Topic
`session_expired`	"Your session has ended. Sign in to continue."	Refresh token TTL hit. `loginWithRedirect()`
`session_revoked`	"Your session has been revoked. Sign in to continue."	Refresh token invalidated. `loginWithRedirect()`
`silent_auth_failed`	(don't show — retry)	Transient; one retry is appropriate

MFA

Code	User-facing copy	Programmatic
`totp_invalid`	"That code didn't work. Check your authenticator app and try again."	Allow re-enter
`webauthn_failed`	"Couldn't verify with your device. Try another method."	Offer fallback factor
`sms_send_failed`	"Couldn't send the code. Try again or use another method."	Offer fallback; check phone format
`sms_rate_limited`	"Too many code requests. Wait a few minutes."	Surface `details.retry_after_s`
`backup_code_invalid`	"That backup code didn't work."	Allow re-enter; remind it's single-use
`flow_expired`	"This sign-in took too long. Start over."	Restart the flow
`flow_invalid`	"Sign-in session lost. Start over."	Restart the flow

Network / platform

Code	User-facing copy	Programmatic
`network_error`	"Connection issue. Check your internet and try again."	Retry with backoff
`rate_limited`	"Too many requests. Try again in a moment."	Honour `Retry-After`
`server_error`	"Something went wrong on our side. Try again shortly."	Retry; consider a circuit breaker
`service_unavailable`	"We're temporarily unavailable. Check status."	Retry; check the platform status page
`not_found`	(varies — usually "Not found.")	Likely config; don't retry

API / data

Code	User-facing copy	Programmatic
`permission_denied`	"You don't have permission to do that."	Don't retry
`validation_failed`	(use `details.fields` to show per-field errors)	Field-level errors
`conflict`	"That resource already exists."	Show what conflicts
`precondition_failed`	"Something changed since you started. Refresh and try again."	Reload and retry

Webhook delivery

These codes appear in your subscription's delivery feed, not in your application code (your code controls the receiver's response).

Platform-side observation	Meaning
`receiver_5xx`	Your receiver returned 5xx. Retry in progress.
`receiver_4xx`	Your receiver returned 4xx (not 2xx); retries continue.
`receiver_timeout`	No response within 10s.
`receiver_tls_failed`	TLS handshake failed.
`dlq_max_attempts`	All retries exhausted; event in DLQ.

See webhook-delivery-failures for the diagnostic tree.

Custom Action (set by your tenant admin on a flow)

These codes appear when a custom Action — configured by your tenant admin on a sign-in or registration flow — blocks, times out, or errors. As an integrator you see the code; your tenant admin sees the Action's stack trace and configuration in the admin console.

Code	When
`step_blocked`	A custom Action returned `block`. `details.step` and `details.reason` identify which Action and why.
`step_timeout`	An Action ran past its wall-clock budget.
`step_error`	An Action threw an exception. The user sees a generic message; the tenant admin has the trace.

How to use this index

Two patterns from production code:

// Pattern 1: switch on code for UX
function userMessage(err: IntelliAuthError): string {
  switch (err.code) {
    case 'invalid_credentials':       return 'Email or password is incorrect.'
    case 'account_locked':            return `Too many attempts. Try again in ${err.details?.retry_after_s ?? 60}s.`
    case 'session_expired':           return 'Your session ended. Sign in to continue.'
    case 'network_error':             return 'Connection issue. Try again.'
    default:                          return 'Something went wrong. Try again shortly.'
  }
}

// Pattern 2: branch on family for retry strategy
function shouldRetry(err: IntelliAuthError): boolean {
  return ['network_error', 'silent_auth_failed', 'server_error', 'service_unavailable'].includes(err.code)
}