code, know which statuses to retry, and distinguish an HTTP error from a factor failure.
Every API error response uses the same JSON envelope:
Request-body validation failures return
422 with code VALIDATION_ERROR and details.errors, a list of {field, message, type}. Treat any 422 as “fix the request body before retrying”.Token endpoint errors
POST /oauth/token is the one exception to the envelope above. It returns standard OAuth 2.0 (RFC 6749) error JSON with Cache-Control: no-store:
error values: invalid_client, invalid_grant, invalid_scope, unsupported_grant_type, invalid_request, temporarily_unavailable.
HTTP status codes
Scope and role denials (403)
A403 means your credential authenticated but is not allowed to make the call:
- The API client’s token does not carry the required
idv:*scope. Check the client’sallowed_scopesand thescopeyou requested. - The console user’s role does not include the required capability (for example, API client management requires the Owner or Admin role).
- The endpoint requires a console session and was called with an API client credential.
Client lockout (429)
Repeated failed authentications lock an API client for a period. While locked, calls return429 with a Retry-After header:
Retry-After and fix the credential before retrying. Retrying with the same bad credential extends the lock and is recorded in the audit trail.
Common error codes
General
Verification requests and links
Sessions (verify)
Configuration and audit
Handling factor failures
Factor execution failures are not HTTP errors.POST /verify/execute returns 200 with success: false and a failure_type that tells the client what to do next:
Retry guidance
- Retry
429,500,502, and503with exponential backoff and jitter; honorRetry-Afterwhen present. - Never retry
4xxerrors other than429without changing the request. POST /integrations/linksreuses an active request for the same user and use case, so retrying it after a timeout is safe. Other create endpoints are not idempotent; check for an existing active request before retrying.

