Skip to main content

Errors

The Verification API uses conventional HTTP status codes and JSON error bodies. Related: SLA and escalation · Troubleshooting

HTTP status codes

Public integration endpoints most often return these codes: 403 (Forbidden) and 409 (Conflict) can appear on internal admin tooling. They are uncommon on the documented consumer routes in this site; treat them as non-retryable if you see them.

Error response format

For validation errors with multiple issues:

Common error scenarios

Authentication errors (401)

Missing Authorization header:
All authentication failures — missing header, malformed token, expired token, invalid signature — collapse to this same generic 401 Unauthorized body. There is no separate “invalid or expired token” message.

Validation errors (400)

Missing required fields:
Invalid date format:
Unsupported search type: Only EMPLOYMENT and EDUCATION are accepted. Requesting CRIMINAL, REFERENCE, or any other value returns searchType must be EMPLOYMENT or EDUCATION for the offending entry — a common validation error worth checking for before you retry.

Order or search not found

Get order and Get specific search return HTTP 200 with an error field in the body when a resource is not found. Check for the error field in addition to the status code. Order not found:
Search not found:

Client handling

Check status codes

Retry logic

Retry transient errors (5xx, network issues) with exponential backoff. Do not retry 4xx — fix the request instead.
Order creation is not idempotent. If a create call fails without a clear response, reconcile by externalSearchId before retrying. See Quickstart — Production readiness.