Troubleshooting

Common issues customers hit during integration, with resolution steps. For HTTP error shapes and retries, see Errors. For SLA and escalation behavior, see 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

Order and validation

Address validation failed

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

{
  "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.

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.

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

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.

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 or email support@snh-ai.com.

Core concepts

Guides

Examples