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) are uncommon on the documented consumer routes; 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:
Invalid search type: Only EMPLOYMENT and EDUCATION are accepted. Any other value returns a validation error.

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.