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

# Troubleshooting

> Common Verification API issues and how to resolve them.

# Troubleshooting

Common issues customers hit during integration, with resolution steps. For HTTP error shapes and retries, see [Errors](/api-reference/errors). For SLA and escalation behavior, see [SLA and escalation](/guides/sla-and-escalation).

## Authentication

| Symptom                                                             | What to try                                                                                                                                                        |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401 Unauthorized`                                                  | Missing or malformed `Authorization: Bearer <jwt>` header                                                                                                          |
| `401` generic `"Unauthorized"` message                              | Request a new sandbox or production JWT from SNH AI. All token-validation failures (expired, malformed, missing signature, etc.) return this same generic message. |
| Token works on `/health` but fails elsewhere                        | Decode the JWT and confirm the **`tenant`** claim is present (your organization's identifier)                                                                      |
| `401` tenant-related failure (missing, unknown, or inactive tenant) | Message is `"Tenant information not found in token"` or `"Tenant validation failed: ..."` — confirm your JWT's **`tenant`** claim, then contact SNH AI             |

Details: [Authentication — Troubleshooting](/getting-started/authentication#troubleshooting)

## Order and validation

### Address validation failed

**Cause:** When `applicant.addresses` is non-empty, exactly one address must be current (`endDate: null` or omitted).

**Solution:**

```json theme={null}
{
  "addresses": [
    {
      "addressType": "home",
      "addressLine1": "123 Main St",
      "addressCity": "San Francisco",
      "addressState": "CA",
      "addressZipCode": "94102",
      "startDate": "2020-01-01",
      "endDate": null
    }
  ]
}
```

Applicant home address is optional — omit `addresses` or send `[]` if you do not need it.

### Invalid date format

**Cause:** Dates must be `YYYY-MM-DD`.

**Solution:** Use that format for birthday, address dates, and employment/education history dates.

### Unsupported search type

**Cause:** Only `EMPLOYMENT` and `EDUCATION` are accepted in `searchTypes`.

**Solution:** Remove `CRIMINAL`, `REFERENCE`, or `history.criminal`. See [Search types](/guides/search-types).

### Duplicate orders after a retry

**Cause:** `POST /orders` is not idempotent.

**Solution:** Send a stable `externalSearchId` per search. If create fails without a response, look up by external ID before resending. See [Quickstart — Production readiness](/quickstart#production-readiness).

## Webhooks

| Symptom                        | What to try                                                                                           |
| ------------------------------ | ----------------------------------------------------------------------------------------------------- |
| Webhooks not received          | Confirm HTTPS URL, matching secret, and that your endpoint is reachable                               |
| Invalid signature              | Verify HMAC over **raw** body bytes; secret must match `webhookConfig.secret` or organization default |
| Events received multiple times | Deduplicate with `X-Event-Id`; retries are expected                                                   |

Full guide: [Webhook Integration — Troubleshooting](/webhooks/integration#troubleshooting)

## Batches

`POST /batches` creates each order independently. Record every returned `verificationOrderId`. Use order endpoints to track and cancel work. See [API overview — batch and event endpoints](/api-reference/background-check/overview#batch-and-event-endpoints).

## Retries — when and how

| Situation                           | Retry?                                                             |
| ----------------------------------- | ------------------------------------------------------------------ |
| `5xx` or network failure            | Yes — exponential backoff                                          |
| `4xx` validation or auth            | No — fix the request or token                                      |
| Order create timed out with no body | Reconcile by `externalSearchId` first, then create only if missing |
| Webhook handler returned `5xx`      | SNH AI retries delivery; make your handler idempotent              |

## Getting help

If you are still blocked, see [Getting help](/getting-started/getting-help) or email [support@snh-ai.com](mailto:support@snh-ai.com).