Errors and status codes

HTTP responses

Check each endpoint reference for operation-specific responses. Also handle authentication, permission, and validation failures.

Status	Handling
200	Request processed; inspect the response body for operation-specific status
400	Read the endpoint-specific reason; it can mean invalid input, unavailable results/report, or an ineligible screening request
401	Missing or invalid API credentials; some operations also return this for missing account context
403	Permission or feature gate prevents the operation
404	Resource unavailable, not found, or hidden from the requesting account
429	If received, honor the server’s retry guidance and reduce request frequency
5xx	Server failure; reconcile uncertain state changes before retrying

Do not assume all errors share one response shape. Error responses can contain strings, validation details, empty bodies, or problem details.

Authentication example

A request to GET /api/ApiClient without an API key returns HTTP 401 with Content-Type: application/problem+json:

{
  "type": "https://httpstatuses.com/401",
  "title": "Unauthorized",
  "status": 401
}

Error formats vary by endpoint. Check the status and content type before parsing the body.

Screening status values

Screening callbacks use BackgroundCheckStatus. Use the Analyst Assistance flow or the flow without Analyst Assistance for your organization’s applicable events:

Value	Meaning and next action
None	No run has started
InQueue	Screening is queued; continue tracking
InProgress	Screening is processing; continue tracking
Redressing	A successful analyst-assisted run is awaiting completion of review
Complete	Successful run; required analyst review has completed
Error	Unsuccessful terminal processing status; investigate before retrying
Redressed	Additional notification when a subject is marked reviewed; the status endpoints return Complete rather than this value

Use the status supplied in the notification and handle duplicates idempotently. Do not require every intermediate state to appear or assume a fixed delivery order. A status recheck after each callback is unnecessary.

The runStatus field in aggregated results uses RunStatusEnum, a different and more detailed enum. Do not compare it to BackgroundCheckStatus values.

Retry decisions

Retry read requests with bounded backoff when appropriate. Avoid repeating permanent validation or permission failures.

For create, configuration updates and other state-changing operations, reconcile uncertain outcomes before retrying. GET /api/ApiClient/refreshApiKey changes state despite its HTTP method. Other workflow-specific actions are covered in the appropriate workflow guide.

Do not rely on an idempotency header to prevent duplicate actions.