Errors, status codes & rate limits
Every status code, the error body, the Retry-After header, and how to back off.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appStatus codes
The API uses conventional HTTP status codes. Note that a 200 can still carry a partial result: when a jurisdiction does not finish, the records from the jurisdictions that did are returned and every jurisdiction is labelled in sourceStatus, rather than failing the whole call. An account needs an active subscription, or free-trial searches left, for a search to run.
| Status | Meaning | When you’ll see it |
|---|---|---|
| 200 | OK | The search ran. status says whether every jurisdiction finished (complete) or at least one did not (partial). |
| 202 | Accepted | Asynchronous search accepted; poll the results URL or await the webhook. |
| 400 | Bad Request | The request cannot be acted on as sent — for example POST /v1/report with neither a searchId nor a query. |
| 401 | Unauthorized | The X-API-Key header is missing or the key is not valid (or, on endpoints that accept one, the dashboard session is not valid). |
| 402 | Payment Required | The account has no active subscription and no free-trial searches left; a free-trial search names no one (a trial search needs a first or last name); a batch has more rows than the trial searches left; or a request sent proof without billing on the account. The detail says which. |
| 403 | Forbidden | Location-only searches (a radius, city, county, ZIP or state with no name) are paused for this account for the rest of the month: detail.code is "location_quota_paused". Searches that include a name are not affected. |
| 404 | Not Found | The search id or record id does not exist, or a report was requested for a searchId this account did not run. |
| 409 | Conflict | GET /v1/records/{recordId} was given a registry uuid that matches records in more than one jurisdiction. The detail names them. |
| 410 | Gone | A verification report was requested for a search older than the 7-day report window, or stored results were requested for a search past the 14-day retention window. |
| 413 | Payload Too Large | A batch has more than 1000 rows. |
| 422 | Unprocessable Entity | The request was understood and DECLINED, and the body says why in a plain sentence you can show a user. Two causes. (a) THE QUERY CANNOT BE ANSWERED COMPLETELY, so it is declined rather than answered with a subset that would read as the whole answer: a query carrying nothing to narrow on cannot be guaranteed to return the same full result twice. Send at least one of lastName, dob, age, city, county, zipcode, address, a lat/lng radius, or q — a firstName or a state on its own is not enough to narrow a search, so pair it with a surname or a date of birth. A name + DOB query is NEVER refused, whatever the name. (b) A parameter is malformed or unrecognised — an unknown jurisdiction code, or a filter placed at the top level of the body instead of inside query. |
| 429 | Too Many Requests | The service is at capacity and did not run the search (detail.code "overloaded"). Nothing was searched and no result is implied. Wait the Retry-After seconds and retry. |
| 504 | Deadline Exceeded | The deadline was hit and the request sent onDeadline = "error"; or the search found no records while at least one registry did not finish (detail.code "incomplete_no_results"), so the empty result is not an answer. |
The error envelope
Every non-2xx response is JSON, and on this API almost always one key, detail(two exceptions: the consumer-account 403 body is {"error","message","path"}, and the live-evidence 503 is {"error":{"code","message"}}; the Criminal Records API uses that error object for every refusal). For most errors detail is a sentence you can log or show a user. When a request fails field validation it is a list, one entry per field, each with loc (the path to the field), msg and type. On a 429 it is an object with a code and retryAfterSeconds; on a 403 and on the 504 whose code is incomplete_no_results it is also an object with a code and a message. Branch on the HTTP status; read detail for the reason. Both shapes are defined field by field in the Error object and the RateLimitError object below.
{
"detail": "Unknown match 'strick'. Allowed: balanced, broad, strict."
}{
"detail": [
{ "type": "date_from_datetime_parsing",
"loc": ["body", "query", "dob"],
"msg": "Input should be a valid date or datetime, input is too short",
"input": "1980" }
]
}422 is a deliberate contract, not a failure. A query with nothing to narrow on cannot be guaranteed to 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. A name + date-of-birth query is never declined, whatever the name.Switching on the code
const res = await fetch(url, { method: "POST", headers, body });
if (!res.ok) {
const { detail } = await res.json();
const reason = typeof detail === "string" ? detail : JSON.stringify(detail);
switch (res.status) {
case 401: throw new Error("Check X-API-Key: " + reason);
case 402: throw new Error("Subscription or billing needed: " + reason);
case 422: return { declined: reason }; // show the user
case 429: return retryAfter(res.headers.get("Retry-After"));
default: throw new Error(`${res.status}: ${reason}`);
}
}
const body = await res.json();
// A 200 can still be partial — read status and counts, never records alone.
if (body.status === "partial") {
// counts.sourcesComplete of counts.sourcesQueried finished
}The Error object — sex offender API error response fields
The error body. detail is a sentence you can log or show; the HTTP status is the value to branch on.
| Field | Type | Description |
|---|---|---|
| detail | string, array or object | What went wrong. A sentence on most errors. A list when the request fails field validation: one entry per field, with loc (the path to the field), msg and type. An object with code, message, unfinishedSources and sourcesQueried on the 504 whose code is incomplete_no_results: the search found no records and at least one registry did not finish, so the empty result is not an answer. An object with code: "location_quota_paused", message, locationRecordsUsed and locationRecordsLimit on the 403 that pauses location-only searches for the month.Example "Missing or invalid API key. Send it in the X-API-Key header." |
The RateLimitError object — 429 rate limit response fields
The 429 Too Many Requests body. The Retry-After header carries the same wait as detail.retryAfterSeconds.
| Field | Type | Description |
|---|---|---|
| detail | object | Why the request was refused and how long to wait. |
| detail.code | string one of "rate_limited", "overloaded" | overloaded: the service is at capacity; no result is implied about the person. rate_limited: a per-caller limit on the contact form and the consumer endpoints, never on search. |
| detail.message | string | A sentence describing the refusal. |
| detail.retryAfterSeconds | integer | Seconds to wait before retrying; equals the Retry-After header. |
| detail.queueDepth | integer or null | Searches queued ahead of this one when it was refused. Present when the search was refused before it ran, and when it ran, found no records and could not finish; absent on the refusal that answers onDeadline: "error". |
| detail.predictedWaitSeconds | number or null | The predicted wait behind that queue, in seconds. Present when the search was refused before it ran; absent on a deadline refusal. |
| detail.unfinishedSources | array of string | Registries that did not finish, when the search ran, found no records and could not complete because the service was at capacity. |
| detail.sourcesQueried | integer | Registries the search queried; sent with unfinishedSources. |
Rate limits & quotas
The search endpoints answer 429 Too Many Requests when the service is at capacity for a request. The search did not run: nothing was searched and the response says nothing about the person. The Retry-After header carries the seconds to wait (1 to 120), and the body repeats it as detail.retryAfterSeconds with detail.code: "overloaded". A search that reaches its deadlineMs with onDeadline: "error" is answered the same way when the service is under load, and with 504 and detail: "Deadline hit and onDeadline=error" otherwise; a search that found nothing before some registries finished answers 504 with detail.code: "incomplete_no_results" (both skipped when you explicitly sent onDeadline: "partial"). Retry after the wait and the same request runs normally.
| Header | Meaning |
|---|---|
| Retry-After | On a 429, seconds to wait before retrying. |
For large jobs, prefer the asynchronous endpoint or batch and spread submissions, rather than issuing thousands of synchronous calls at once. Handle 429 with exponential backoff that respects Retry-After.
import time, requests
def search(payload, key, attempts=5):
for attempt in range(attempts):
r = requests.post(
"https://api.offendersearch.app/v1/search",
headers={"X-API-Key": key},
json=payload,
timeout=130,
)
if r.status_code != 429:
r.raise_for_status()
return r.json()
wait = int(r.headers.get("Retry-After", 2 ** attempt))
time.sleep(wait)
raise RuntimeError("rate limited after %d attempts" % attempts)Retrying safely
A retry should never start — or bill — a second search. On POST /v1/searches every accepted request is a new job, so store the searchId from the 202 and poll it rather than submitting again. A 429 whose body carries detail.queueDepth was refused before a result was produced and was not billed, so retrying it after Retry-After is safe.
When a response comes back partial, the thing to read is not the status word but sourceStatus[].incompleteReason: it is a closed enum, and each value says whether retrying the identical request will change the answer. Result completeness sets out every value and the action it implies.