Errors
Every status and stable error code, and what to do about each.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appError codes
Every refusal the FCRA API raises itself returns { "detail": { "code": "…", "message": "…" } }: switch on detail.code, show detail.message. Two refusals carry a plain string in detail instead: a missing or invalid key (401), and a dashboard team member who is not an admin changing the webhook endpoint (403). A body that fails field validation returns 422 with detail as an array of { loc, msg, type } entries, one per problem.
| Status | Code | Meaning |
|---|---|---|
| 401 | — | Missing or invalid X-API-Key. detail is a string. |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_purpose_not_allowed | The purpose is not in your agreement, or not held by the end user. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
| 404 | not_found | No such end user, order, search, dispute, event or evidence capture on your account. |
| 404 | unknown_end_user | The endUserId is not one of your end users. |
| 409 | idempotency_conflict | The Idempotency-Key was used with a different body. |
| 409 | not_cancellable | The order is already complete, error or cancelled. |
| 409 | report_not_ready | The report and its PDF are available once the order is complete or error. |
| 409 | search_not_finished | Only a finished search can be re-verified. |
| 409 | order_cancelled | The order was cancelled. |
| 409 | dispute_not_extendable | The dispute is resolved, already extended, or past due. |
| 422 | — (array) | A field failed validation: a partial or future date of birth, a missing or future consent attestation, an unknown search type, purpose or liveScope, a repeated search type, a callbackUrl or webhook URL that is not https://, a dispute receivedAt in the future, or an unexpected field. detail lists each problem. |
| 422 | validation | An Idempotency-Key over 200 characters. |
| 422 | end_user_suspended | The end user is suspended. |
| 422 | unknown_record | A recordIds entry was not furnished in this order. |
| 422 | webhook_endpoint_required | A callbackUrl needs a configured webhook endpoint first. |
| 422 | ssn_required | addressSource: "ssn_trace" (or the end user’s default) and no subject.ssn; on the hosted page, an SSN-trace invitation completed without one. |
| 422 | ssn_trace_unavailable | SSN trace is not on for this account yet. Place the order or invitation with addressSource: "provided". |
| 422 | ssn_not_used_in_address_mode | An SSN was sent with addressSource: "provided". It is not echoed back. |
| 422 | addresses_required | addressSource: "provided" was chosen and no address was sent. |
| 422 | live_scope_not_enabled | liveScope: "matches" is not enabled for this account yet. Nothing was placed or sent; send relevant or all, or ask us to enable it. |
| 422 | — (array) | Healthcare search: exclusions: "none" on a healthcare search, an npi that is not 10 digits or fails its check digit, a licenses entry without a two-letter state or a number, or more than 10 licenses. |
| 503 | receipts_unavailable | Receipt signing is unavailable; retry later. |
| 401 | not_matched | Consumer portal: the access code, last name and date of birth do not all match an order, or the order was cancelled. The message is the same whatever was wrong. |
| 401 | no_session · session_expired | Consumer portal: no session token, or the session has ended (after 30 minutes, or because the order was cancelled). |
| 429 | locked | Consumer portal: five failed attempts within an hour for this code or from this IP address. |
| 429 | rate_limited | Consumer portal or consumer request: too many requests in a short period. Retry later. |
| 422 | unexpected_fields · invalid | Consumer request: a field other than the six accepted, or a missing or invalid field (including a message with a Social Security number). |
An order refused for its purpose (fcra_purpose_not_allowed) is still written to the evidence record, with the reason it was refused.
live_unavailable is not an error: it is an incompleteReasons value on a completed search whose relevant jurisdiction could not be searched live. The search completes with result incomplete.
verification_pending is not an error either: on a liveScope: "matches" search it means a possible record is held while its source agency confirms it. The search completes with result incomplete and is updated when the agency answers.
no_source_searched and freshness_unknown are not errors either: they are incompleteReasons values on a completed search that could not search what it needed to — every relevant criminal source was a coverage gap, or a healthcare list has no refresh on record. The search completes incomplete; order again later.
identifiers_needed is not an error: on a healthcare search it means a list entry matched the consumer’s name but nothing else. The search completes incomplete; order again with the consumer’s npi or licenses.
The Error object — FCRA API error response fields
Every refusal the FCRA API raises itself. Switch on detail.code; show detail.message. A body that fails field validation returns the standard validation body instead, where detail is an array of { loc, msg, type } entries.
| Field | Type | Description |
|---|---|---|
| detail | object | The refusal. |
| detail.code | string | The stable code to switch on, for example fcra_not_enabled.Example "fcra_not_enabled" |
| detail.message | string | A sentence you can show. |