Skip to main content
This page is for the engineer handling responses from the TruU IDV API. When you finish, you can branch on 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:
Possible error values: invalid_client, invalid_grant, invalid_scope, unsupported_grant_type, invalid_request, temporarily_unavailable.

HTTP status codes

Scope and role denials (403)

A 403 means your credential authenticated but is not allowed to make the call:
Common causes:
  • The API client’s token does not carry the required idv:* scope. Check the client’s allowed_scopes and the scope you 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 return 429 with a Retry-After header:
Wait out 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

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:
Repeated factor failures count toward a per-user lockout. Once locked, new session starts are rejected until the lockout window elapses. Do not build automatic retry loops around factor execution.

Retry guidance

  • Retry 429, 500, 502, and 503 with exponential backoff and jitter; honor Retry-After when present.
  • Never retry 4xx errors other than 429 without changing the request.
  • POST /integrations/links reuses 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.