Errors & Rate Limits

Use the code field in the error response body to drive error-handling logic in your integration. The message field is human-readable and intended for logging and debugging.

HTTP errors

Error response format

Most error responses return an error object with a machine-readable code and a message:

{
  "error": {
    "code": "incorrect_parameters",
    "message": "Incorrect request parameters",
    "extra": {
      "invalid-params": []
    }
  }
}

The extra field appears on 400 responses only. It lists the specific fields that failed validation.

404 responses use a different shape: {"detail": "Not Found."} rather than the standard error object.

Status codes

Status	`error.code`	Description
`400 Bad Request`	`incorrect_parameters`	A required field is missing, a field value is invalid, or a combination of fields is not allowed. Check `extra.invalid-params` for specifics.
`401 Unauthorized`	`authentication_failed`	The `X-Access-Client-Id` or `X-Access-Secret` header is missing, malformed, or the credentials do not match any key in the environment.
`403 Forbidden`	`not_authenticated`	Credentials are valid but do not have permission to access this resource. Common cause: using sandbox credentials against a production resource.
`404 Not Found`	(see above)	The requested resource ID does not exist or belongs to a different client.
`405 Method Not Allowed`	—	The HTTP method is not supported on this endpoint. Check the API Reference for the supported method.
`406 Not Acceptable`	—	The server can’t produce a response matching the `Accept` header in your request. Truv responses are always `application/json` — remove restrictive `Accept` headers.
`410 Gone`	`expired_token`	A token used in the Bridge flow is no longer valid. Most often a `public_token` exchange after expiry or reuse — see the 410 Gone response example for recovery.
`415 Unsupported Media Type`	—	The request payload format is unsupported. Set `Content-Type: application/json` and send a valid JSON body.
`429 Too Many Requests`	`throttled`	Request rate limit exceeded. Back off and retry. See Rate limits.
`500 / 502 / 503`	—	Truv-side error. Retry with exponential backoff. If errors persist, check status and contact support@truv.com.

Response examples

400 Bad Request

Each entry in invalid-params carries a field (the offending parameter name) and a message (the validation reason).

{
  "error": {
    "code": "incorrect_parameters",
    "message": "Incorrect request parameters",
    "extra": {
      "invalid-params": [
        { "field": "products", "message": "This field is required." },
        { "field": "user.email", "message": "Enter a valid email address." }
      ]
    }
  }
}

401 Unauthorized

{
  "error": {
    "code": "authentication_failed",
    "message": "No such token"
  }
}

403 Forbidden

{
  "error": {
    "code": "not_authenticated",
    "message": "Authentication credentials were not provided."
  }
}

404 Not Found

{
  "detail": "Not Found."
}

410 Gone

The most common trigger is calling POST /v1/link-access-tokens/ with a public_token that was already exchanged or has aged out — public_token is single-use and short-lived. Less commonly, the upstream bridge_token has expired (valid for 6 hours from creation).

{
  "error": {
    "code": "expired_token",
    "message": "Public token expired: 48427a36d43c4d5aa6324bc06c692456"
  }
}

Recovery

Token	Action
`public_token` expired or reused	Re-run Truv Bridge so `onSuccess` returns a fresh `public_token`, then exchange it immediately at `POST /v1/link-access-tokens/`.
`bridge_token` expired	Call Create Bridge Token for a new `bridge_token`, then re-initialize Bridge on the client.

See the bridge_token → public_token → access_token flow for the full token lifecycle.

429 Too Many Requests

{
  "error": {
    "code": "throttled",
    "message": "Request was throttled."
  }
}

Rate limits

Truv applies rate limits to protect platform stability and to keep latency predictable for every customer. Limits apply per Truv account and are evaluated per environment — sandbox and production are tracked separately.

Standard limits

Surface	Limit	Scope
Orders API — Create + Retrieve combined	300 requests / minute	Per Truv account, per environment
Refresh endpoints, per `access_token`	1 initial request + 3 refreshes per 24 hours	Per `access_token`

The Orders limit applies to the combined volume of POST /v1/orders/ and GET /v1/orders/{id}/ calls. For example, 200 creates plus 200 retrieves in the same minute exceeds the limit. The per-access_token refresh limit covers POST /v1/refresh/tasks/ and GET /v1/refresh/tasks/{task_id}/, plus GET /v1/links/{access_token}/ re-fetches. Requests beyond the allowed window return the error message Refresh limit for the access_token exceeded. See the canonical Links and Refresh reference pages for the per-endpoint detail.

These are the defaults for new accounts. Higher limits are available — see Request a higher limit below.

Handle 429 responses

When a request exceeds a rate limit, Truv returns 429 Too Many Requests with error.code: throttled. The connection is not penalized — subsequent requests succeed once your traffic drops back under the limit. Respect the Retry-After response header on 429 responses. The value is the number of seconds to wait before retrying. If the header is not present, fall back to exponential backoff starting at 1 second and capped at 60 seconds.

# Pseudocode — Retry-After backoff with exponential fallback (capped at 60s)
attempt = 0
loop:
    response = HTTP request
    if response.status != 429:
        return response

    retry_after = response.headers.get("Retry-After")          # seconds, if Truv supplied it
    fallback    = min(2 ** attempt, 60)                        # 1, 2, 4, 8, 16, 32, 60, 60, ...
    sleep(int(retry_after) if retry_after else fallback)
    attempt += 1

Always check the response status before sleeping. The pseudocode above retries only on 429; on 5xx responses, Truv-side error retry guidance applies instead. On 2xx or 4xx other than 429, return the response immediately — never retry blindly.

Best practices

Webhooks over polling. Polling GET /v1/orders/{id}/ for status changes is the most common cause of 429 in production. Subscribe to order-status-updated and task-status-updated and only call the GET endpoint when a webhook fires.
Stagger batch jobs. Spread bulk Order creation across the hour rather than all at once. A 50,000-Order batch at 833 RPM trips the limit; the same batch at 250 RPM completes within it.
Refresh deliberately. The per-access_token refresh limit is designed for human-paced re-verification. Programmatic refresh on every page load exhausts the limit within minutes.
Don’t retry blindly. Order creation is not idempotent — retrying a failed POST /v1/orders/ creates a new Order. Store your application-level reference and de-duplicate before retrying.

Request a higher limit

Higher limits are available on request. To request one, contact your Truv Technical Account Manager or email support@truv.com with:

Truv account name and environment (sandbox or production).
Current peak RPM and target peak RPM.
Time window when peaks occur (e.g., 7–9 PM ET on weekdays).
Use case context — e.g., “Recertification batch — 50,000 applicants over a 4-hour window.”

Task error states

For all task error states, their causes, and recommended actions, see Task Lifecycle — Error states. Subscribe to task-status-updated webhooks to receive error notifications in real time.

Bridge errors

Truv Bridge fires client-side errors through the onEvent callback when type === 'ERROR'. These are distinct from task error states — they fire in the browser during the connection flow, not through webhooks.

onEvent: function(type, payload) {
  if (type === 'ERROR') {
    console.error(payload.error.error_code, payload.error.error_message);
  }
}

For the full error code reference (LOGIN_ERROR, MFA_ERROR, UNAVAILABLE, NO_DATA, LINK_EXISTS, ERROR), error object shape, and recommended fallback routing, see Bridge Events — Errors.

Document processing errors

For document upload errors — config_error and no_data messages, fraud detection, and the complete review workflow — see Fraud & Manual Review.

Webhook delivery retries

For webhook timeout, retry policy, and signature verification, see Webhooks — delivery and retries.

Next steps

Task Lifecycle

Complete task status flow and error state transitions

Bridge Events

Client-side error codes and fallback routing

Fraud & Manual Review

Document fraud detection and review workflows

Webhook Events

Real-time notifications for task and order status changes

API Reference

Platform

Income & Employment

Financial Accounts

Document Processing

Direct Deposit Switch

Insurance Verification

Errors & Rate Limits

HTTP errors

Error response format

Status codes

Response examples

Rate limits

Standard limits

Handle 429 responses

Best practices

Request a higher limit

Task error states

Bridge errors

Document processing errors

Webhook delivery retries

Next steps

Task Lifecycle

Bridge Events

Fraud & Manual Review

Webhook Events

API Reference

Platform

Income & Employment

Financial Accounts

Document Processing

Direct Deposit Switch

Insurance Verification

Documentation Index

​HTTP errors

​Error response format

​Status codes

​Response examples

​Rate limits

​Standard limits

​Handle 429 responses

​Best practices

​Request a higher limit

​Task error states

​Bridge errors

​Document processing errors

​Webhook delivery retries

​Next steps

Task Lifecycle

Bridge Events

Fraud & Manual Review

Webhook Events

HTTP errors

Error response format

Status codes

Response examples

Rate limits

Standard limits

Handle 429 responses

Best practices

Request a higher limit

Task error states

Bridge errors

Document processing errors

Webhook delivery retries

Next steps