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:

Status Code	Description
`200`	Success — request completed successfully
`201`	Created — resource created successfully
`400`	Bad Request — invalid parameters or missing required fields
`401`	Unauthorized — invalid or missing authentication
`404`	Not Found — resource doesn’t exist (some read endpoints return `200` with an `error` body instead — see below)
`500`	Internal Server Error — something went wrong on our end

403 (Forbidden) and 409 (Conflict) are uncommon on the documented consumer routes; treat them as non-retryable if you see them.

Error response format

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "code": "HTTP_BAD_REQUEST",
  "requestId": "3f2b8c1e-5a47-4d0e-9b61-7c2d4e8f1a90"
}

Field	Description
`statusCode`	The HTTP status code.
`message`	A human-readable message, or an array of messages for validation errors. Do not parse it; wording can change.
`error`	The HTTP status name, when present.
`code`	A stable, machine-readable code. Branch on this, not on `message`. Where an endpoint returns its own `code`, that value is kept.
`requestId`	Identifies this request in our logs. Include it when you contact support. Also returned in the `x-request-id` response header.

The code values returned for general failures are HTTP_VALIDATION_FAILED, HTTP_BAD_REQUEST, AUTH_UNAUTHORIZED, AUTH_FORBIDDEN, HTTP_NOT_FOUND, HTTP_CONFLICT, HTTP_RATE_LIMITED, HTTP_SERVICE_UNAVAILABLE, HTTP_INTERNAL_ERROR, and HTTP_CLIENT_ERROR. code and requestId are additive: every other field is unchanged, and the examples below omit them for brevity. Ignore any fields you do not recognize.

Tracing a request

Send an x-request-id header (1–128 characters: letters, digits, ., _, :, -) and we use it as the request id, so the same id appears in your logs and ours. If you send none, or an invalid value, we generate one. Either way it is echoed in the x-request-id response header. For validation errors with multiple issues:

{
  "statusCode": 400,
  "message": ["proposedSalary must be a number", "applicant.ssn should not be empty"],
  "error": "Bad Request"
}

Common error scenarios

Authentication errors (401)

Missing Authorization header:

{
  "statusCode": 401,
  "message": "Unauthorized"
}

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:

{
  "statusCode": 400,
  "message": ["applicant.firstName should not be empty", "applicant.ssn should not be empty", "entityName should not be empty"],
  "error": "Bad Request"
}

Invalid date format:

{
  "statusCode": 400,
  "message": ["history.employment.0.startDate must be a valid date in YYYY-MM-DD format"],
  "error": "Bad Request"
}

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:

{
  "error": "Order not found",
  "orderId": "123e4567-e89b-12d3-a456-426614174000"
}

Search not found:

{
  "error": "Search not found",
  "orderId": "123e4567-e89b-12d3-a456-426614174000",
  "searchId": "456e7890-e89b-12d3-a456-426614174001"
}

Client handling

Check status codes

const response = await fetch('https://sandbox.theary.ai/background-check/v1/orders', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(orderData),
})

if (!response.ok) {
  const errorData = await response.json()
  console.error('API Error:', errorData)

  switch (response.status) {
    case 400:
      console.error('Validation Error:', errorData.message)
      break
    case 401:
      console.error('Authentication Error - Check your token')
      break
    case 404:
      console.error('Resource not found')
      break
    default:
      console.error('Unexpected error:', response.status)
  }

  throw new Error(`API Error: ${response.status}`)
}

const data = await response.json()

Retry logic

Retry transient errors (5xx, network issues) with exponential backoff. Do not retry 4xx — fix the request instead.

async function createOrderWithRetry(orderData, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    let response
    try {
      response = await fetch('https://sandbox.theary.ai/background-check/v1/orders', {
        method: 'POST',
        headers: {
          Authorization: 'Bearer YOUR_JWT_TOKEN',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(orderData),
      })
    } catch (error) {
      // Network failure — retry with backoff
      if (attempt === maxRetries) throw error
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000))
      continue
    }

    if (response.ok) {
      return await response.json()
    }

    // Do not retry client errors — fix the request or token instead
    if (response.status >= 400 && response.status < 500) {
      throw new Error(`Client Error: ${response.status}`)
    }

    if (attempt === maxRetries) {
      throw new Error(`Server Error after ${maxRetries} attempts: ${response.status}`)
    }

    await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000))
  }
}

Order creation is not idempotent. If a create call fails without a clear response, reconcile by externalSearchId before retrying. See Quickstart — Production readiness.

Overview

Orders API

Search Management

Batches API

Inbound API

Files API

Closeout Events API

Request and order schemas

Webhook schemas

Errors

Errors

HTTP status codes

Error response format

Tracing a request

Common error scenarios

Authentication errors (401)

Validation errors (400)

Order or search not found

Client handling

Check status codes

Retry logic

​Errors

​HTTP status codes

​Error response format

​Tracing a request

​Common error scenarios

​Authentication errors (401)

​Validation errors (400)

​Order or search not found

​Client handling

​Check status codes

​Retry logic

Errors

HTTP status codes

Error response format

Tracing a request

Common error scenarios

Authentication errors (401)

Validation errors (400)

Order or search not found

Client handling

Check status codes

Retry logic