FCRA Partner API · v1.0.0 · approved partners

Errors

Every status and stable error code, and what to do about each.

Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.app

Error 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.

StatusCodeMeaning
401—Missing or invalid X-API-Key. detail is a string.
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_purpose_not_allowedThe purpose is not in your agreement, or not held by the end user.
403fcra_not_on_trialFCRA orders are not available on a trial account.
404not_foundNo such end user, order, search, dispute, event or evidence capture on your account.
404unknown_end_userThe endUserId is not one of your end users.
409idempotency_conflictThe Idempotency-Key was used with a different body.
409not_cancellableThe order is already complete, error or cancelled.
409report_not_readyThe report and its PDF are available once the order is complete or error.
409search_not_finishedOnly a finished search can be re-verified.
409order_cancelledThe order was cancelled.
409dispute_not_extendableThe 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.
422validationAn Idempotency-Key over 200 characters.
422end_user_suspendedThe end user is suspended.
422unknown_recordA recordIds entry was not furnished in this order.
422webhook_endpoint_requiredA callbackUrl needs a configured webhook endpoint first.
422ssn_requiredaddressSource: "ssn_trace" (or the end user’s default) and no subject.ssn; on the hosted page, an SSN-trace invitation completed without one.
422ssn_trace_unavailableSSN trace is not on for this account yet. Place the order or invitation with addressSource: "provided".
422ssn_not_used_in_address_modeAn SSN was sent with addressSource: "provided". It is not echoed back.
422addresses_requiredaddressSource: "provided" was chosen and no address was sent.
422live_scope_not_enabledliveScope: "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.
503receipts_unavailableReceipt signing is unavailable; retry later.
401not_matchedConsumer 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.
401no_session · session_expiredConsumer portal: no session token, or the session has ended (after 30 minutes, or because the order was cancelled).
429lockedConsumer portal: five failed attempts within an hour for this code or from this IP address.
429rate_limitedConsumer portal or consumer request: too many requests in a short period. Retry later.
422unexpected_fields · invalidConsumer 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.

FieldTypeDescription
detail
objectThe refusal.
detail.code
stringThe stable code to switch on, for example fcra_not_enabled.
Example "fcra_not_enabled"
detail.message
stringA sentence you can show.

Product overview