> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error envelope, HTTP status codes, OAuth token endpoint errors, scope and lockout responses, the common error code reference, and how to handle factor failures in the TruU IDV API.

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:

```json theme={null}
{
  "code": "REQUEST_EXPIRED",
  "message": "Verification request has expired.",
  "details": null
}
```

| Field | Type | Description |
| - | - | - |
| `code` | string | Stable, machine-readable error code. Branch on this, not on `message`. |
| `message` | string | Human-readable explanation. Wording may change. |
| `details` | object or null | Optional structured context (for example, the offending field or a validation result). |

> [!NOTE]
>
> 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`:

```json theme={null}
{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}
```

Possible `error` values: `invalid_client`, `invalid_grant`, `invalid_scope`, `unsupported_grant_type`, `invalid_request`, `temporarily_unavailable`.

## HTTP status codes

| Code | Meaning | Retry? |
| - | - | - |
| `200` | Success. | N/A |
| `201` | Resource created. | N/A |
| `204` | Success, no body. | N/A |
| `400` | Bad request: malformed input or a violated business rule. | No, fix the request. |
| `401` | Authentication missing, expired, or invalid. | No, fix credentials. |
| `403` | Authenticated but lacking the required role or scope. | No |
| `404` | Resource not found, or it belongs to another organization. | No |
| `409` | Conflict with current state (already finalized, already exists). | No |
| `410` | Resource gone: the request or link expired or failed. | No |
| `422` | Request body failed validation. | No, fix the request. |
| `429` | Rate limit exceeded or client locked. | Yes, honor `Retry-After`. |
| `500` | Internal server error. | Yes, exponential backoff. |
| `502` | An upstream provider (for example, the directory) could not be reached. | Yes, exponential backoff. |
| `503` | A downstream service is unavailable (for example, SMS or email delivery). | Yes, exponential backoff. |

## Scope and role denials (403)

A `403` means your credential authenticated but is not allowed to make the call:

```json theme={null}
{
  "code": "INSUFFICIENT_PERMISSIONS",
  "message": "Insufficient permissions",
  "details": null
}
```

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:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: <seconds>
Content-Type: application/json

{
  "code": "M2M_CLIENT_LOCKED",
  "message": "Client temporarily locked after repeated failed authentications.",
  "details": null
}
```

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

| Code | Status | Meaning |
| - | - | - |
| `AUTHENTICATION_ERROR` | 401 | Bearer credential missing, malformed, expired, or revoked. |
| `INSUFFICIENT_PERMISSIONS` | 403 | The credential lacks the required role or scope. |
| `M2M_CLIENT_LOCKED` | 429 | The client is locked after repeated failed authentications. At `POST /oauth/token`, a locked client gets the OAuth error `temporarily_unavailable` instead. |
| `NOT_FOUND` | 404 | The resource does not exist in your organization. |
| `CONFLICT` | 409 | The request conflicts with existing state. |
| `GONE` | 410 | The resource is permanently unavailable. |
| `VALIDATION_ERROR` | 422 | The payload failed domain-level validation. |
| `SECURITY_ERROR` | 400 | Generic security failure. |
| `SERVICE_UNAVAILABLE` | 503 | A downstream dependency is unavailable. |
| (500) | 500 | Unexpected server error. The body is `{"detail": "Internal server error"}`, not the standard envelope. |

### Verification requests and links

| Code | Status | Meaning |
| - | - | - |
| `REQUEST_NOT_FOUND` | 404 | No verification request with that ID. |
| `TOKEN_NOT_FOUND` | 404 | The short link token does not resolve to a request. |
| `REQUEST_EXPIRED` | 410 | The request expired before completion. |
| `REQUEST_FAILED` | 410 | The request already failed. |
| `REQUEST_CANCELLED` | 410 | The request was cancelled (for example, by a help desk agent). |
| `REQUEST_DECLINED` | 410 | The request was declined. |
| `ALREADY_VERIFIED` | 409 | The request already completed successfully. |
| `USER_NOT_IN_DIRECTORY` | 404 | The user does not exist in the organization's directory. |
| `NO_EMAIL_ON_RECORD` | 422 | Email delivery selected but the directory has no email for the user. |
| `NO_MOBILE_ON_RECORD` | 422 | SMS delivery selected but the directory has no mobile number for the user. |
| `EMAIL_DELIVERY_FAILED` | 503 | The email provider rejected or failed the send. |
| `SMS_DELIVERY_FAILED` | 503 | The SMS provider rejected or failed the send. |

### Sessions (verify)

| Code | Status | Meaning |
| - | - | - |
| `PREFLIGHT_FAILED` | 422 | A blocking preflight check failed at session start; `message` carries the first failure. |
| `INVALID_DOMAIN_ID` | 422 | The domain identifier is not a valid GUID. |
| `SESSION_MISMATCH` | 422 | `session_id` in the body does not match the session token. |
| `VERIFY_CLAIM_HELD` | 409 | The link is already open on another device or browser. Close it there, wait about a minute, then reload, or issue a new link. |
| `VERIFY_TAB_HELD` | 409 | The link is already open in another tab of the same browser. Finish there, or close that tab and retry. |
| `VERIFY_SESSION_MISMATCH` | 409 | The session is no longer the request's active session (a newer session superseded it). Reload the link. |
| `INVALID_COLUMN` | 422 | `column_id` is not one of the session's applicable columns. |
| `INVALID_FACTOR` | 422 | `factor_definition_id` is not in the chosen column. |
| `WRONG_FACTOR_ORDER` | 422 | Factors in a column must be completed sequentially. |
| `COLUMN_INCOMPLETE` | 422 | Completion requested before all factors in the column succeeded. |
| `NOT_VERIFICATION_SESSION` | 422 | The session token does not belong to a verification session. |
| `INVALID_FACTOR_TYPE` | 422 | `factor_type` must be `sms` or `email` for contact preview. |

### Configuration and audit

| Code | Status | Meaning |
| - | - | - |
| `FACTOR_CONFIG_INVALID` | 422 | The merged factor configuration failed schema validation. |

## 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:

| `failure_type` | Client behavior |
| - | - |
| `retry` | Transient: let the user attempt the same factor again. |
| `terminal` | The factor cannot succeed on this device or session; fall back to the next applicable column. |
| `fatal` | Unrecoverable: the session has failed; do not continue. |

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.