Criminal Records API · v1.0.0

Errors & status codes

Every status code, the stable error envelope, and why a 200 can still be an incomplete live search.

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

The error shape

Criminal endpoints return errors as a single, consistent nested object across every endpoint: a stable error.code you switch on and a human-readable error.message you can surface. One handler covers the whole product. Branch on code, render message — code is a stable machine token; the wording of message can change. The two exceptions are 401 and 402: the gateway answers those before Criminal Search runs, in the flat {"detail": "…"} shape the Sex Offender API uses — see the GatewayError object.

422 Unprocessable Entity
{
  "error": {
    "code": "guard_unbounded_query",
    "message": "a lastName predicate is required — an unbounded query returns a lottery, not an answer"
  }
}

A 200 can still describe an incomplete live search: read status and counts, never records alone.

Status codes

Statuserror.codeWhen you’ll see it
200—A cached search, or a synchronous live search, completed. A cached search is always complete; a live search may report unfinished sources in counts.
202—A live search that runs as an async job — more than two sources, or any source that cannot answer in-request; poll GET /v1/criminal/searches/{searchId} for the result.
400no_report_inputA report request with neither a searchId nor an inline query.
401— (detail)The X-API-Key header is missing or not a valid key. The gateway answers before Criminal Search runs, so the body is the flat GatewayError {"detail": "..."}.
402— (detail)The free trial is used up, or the account has no active subscription. Same flat GatewayError body; the sentence says which, and what to do.
404not_foundNo search or record carries the id you asked for, or it belongs to another account.
413batch_too_largeA batch of more than 1000 rows.
422guard_unbounded_queryquery.lastName is missing — an unbounded query is declined rather than answered with a lottery.
422prefix_too_shortAn explicit name-prefix search below the three-character floor.
422invalid_dobquery.dob is not a YYYY-MM-DD date.
422invalid_pagepage is below 1, or perPage is not an integer from 1 to 200. In a batch, that row comes back as an error row instead.
422no_live_sourcesA live block that named nothing to check: an empty jurisdictions list, or scope "matched" when the cached search found no records — and no website was sent.
422no_websiteA resolve call with neither website nor websites.
422query_too_broadThe name and filters match more stored records than one search can read in full within its time budget. Refused rather than answered partially; detail says what to add (firstName or state). In a batch, that row comes back as an error row instead.
422bad_batch / empty_batchAn unparseable batch body or a CSV with no header row, or zero queries in the batch.
503unavailableCriminal Search could not be reached. Retry with backoff.
503catalog_unavailableGET /v1/criminal/sources could not read the source catalog. Retry with backoff.
504upstream_timeoutCriminal Search did not answer within 65 seconds, or the connection to it failed. Retry, or narrow the query.

Rate limiting is a queue first, a refusal second. The gateway holds a request for up to 45 seconds when the service is busy, so you rarely see a limit at all. When it does refuse — 429 from the gateway or 503 with {"error":{"code":"retry"}} from the service — the response carries a Retry-After header; wait that long and resend. Nothing was searched and nothing was billed. Keep your own concurrency modest: a cached search over a common surname can return up to 200 records per page and many pages.

Two errors, verbatim

Missing or invalid key
401 Unauthorized
{
  "detail": "Provide a valid X-API-Key or session token."
}
Declined query
422 Unprocessable Entity
{
  "error": {
    "code": "guard_unbounded_query",
    "message": "a lastName predicate is required — an unbounded query returns a lottery, not an answer"
  }
}
422 is a deliberate contract, not a failure. A query with nothing to narrow on cannot return the same full result twice, so it is declined with a sentence you can show a user rather than answered with a subset that would read as the whole answer.

The criminal Error object — API error response fields

The body of every error the criminal service returns: one nested error object with a stable code to branch on and a message to log or show. A 401 or 402 comes from the gateway in the GatewayError shape instead.

FieldTypeDescription
error
objectThe error. Always present on a criminal-service error.
error.code
string
one of "no_report_input", "not_found", "batch_too_large", "guard_unbounded_query", "prefix_too_short", "no_live_sources", "no_website", "bad_batch", "empty_batch", "query_too_broad", "invalid_dob", "invalid_page", "invalid_body", "invalid_query", "invalid_live", "invalid_filter_value", "invalid_date_range", "invalid_location", "too_many_locations", "ambiguous_location", "radius_too_large", "filters_with_async_live", "invalid_group_by", "invalid_parameter", "stats_internal_only", "unavailable", "catalog_unavailable", "filters_unavailable", "stats_unavailable", "retry", "upstream_timeout"
Stable machine token. Branch on this, never on message. 400 no_report_input, 403 stats_internal_only, 404 not_found, 413 batch_too_large, 422 for guard_unbounded_query · prefix_too_short · invalid_dob · invalid_page · invalid_body · invalid_query · invalid_live · no_live_sources · no_website · bad_batch · empty_batch · query_too_broad · invalid_filter_value · invalid_date_range · invalid_location · too_many_locations · ambiguous_location · radius_too_large · filters_with_async_live · invalid_group_by · invalid_parameter, 503 for unavailable · catalog_unavailable · filters_unavailable · stats_unavailable, 504 upstream_timeout.
Example "guard_unbounded_query"
error.message
stringOne human-readable sentence saying what was wrong. Its wording can change; log it, do not parse it.
Example "a lastName predicate is required — an unbounded query returns a lottery, not an answer"

The GatewayError object — 401 and 402 bodies

The body of a 401 (missing or invalid X-API-Key) or a 402 (free trial used up, or no active subscription). The gateway answers these before the criminal service runs, so the shape is the Sex Offender API's flat detail string.

FieldTypeDescription
detail
stringOne sentence naming the problem and the next step: send a valid key, add a payment method, or start a subscription.
Example "Provide a valid X-API-Key or session token."

Product overview