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.appThe 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.
{
"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
| Status | error.code | When 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. |
| 400 | no_report_input | A 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. |
| 404 | not_found | No search or record carries the id you asked for, or it belongs to another account. |
| 413 | batch_too_large | A batch of more than 1000 rows. |
| 422 | guard_unbounded_query | query.lastName is missing — an unbounded query is declined rather than answered with a lottery. |
| 422 | prefix_too_short | An explicit name-prefix search below the three-character floor. |
| 422 | invalid_dob | query.dob is not a YYYY-MM-DD date. |
| 422 | invalid_page | page 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. |
| 422 | no_live_sources | A 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. |
| 422 | no_website | A resolve call with neither website nor websites. |
| 422 | query_too_broad | The 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. |
| 422 | bad_batch / empty_batch | An unparseable batch body or a CSV with no header row, or zero queries in the batch. |
| 503 | unavailable | Criminal Search could not be reached. Retry with backoff. |
| 503 | catalog_unavailable | GET /v1/criminal/sources could not read the source catalog. Retry with backoff. |
| 504 | upstream_timeout | Criminal 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
{
"detail": "Provide a valid X-API-Key or session token."
}{
"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.
| Field | Type | Description |
|---|---|---|
| error | object | The 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 | string | One 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.
| Field | Type | Description |
|---|---|---|
| detail | string | One 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." |