Sex Offender Search API · v1.0.0

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

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

StatusMeaningWhen you’ll see it
200OKThe search ran. status says whether every jurisdiction finished (complete) or at least one did not (partial).
202AcceptedAsynchronous search accepted; poll the results URL or await the webhook.
400Bad RequestThe request cannot be acted on as sent — for example POST /v1/report with neither a searchId nor a query.
401UnauthorizedThe X-API-Key header is missing or the key is not valid (or, on endpoints that accept one, the dashboard session is not valid).
402Payment RequiredThe 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.
403ForbiddenLocation-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.
404Not FoundThe search id or record id does not exist, or a report was requested for a searchId this account did not run.
409ConflictGET /v1/records/{recordId} was given a registry uuid that matches records in more than one jurisdiction. The detail names them.
410GoneA 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.
413Payload Too LargeA batch has more than 1000 rows.
422Unprocessable EntityThe 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.
429Too Many RequestsThe 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.
504Deadline ExceededThe 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.

Declined or unrecognised value
422 Unprocessable Entity
{
  "detail": "Unknown match 'strick'. Allowed: balanced, broad, strict."
}
Field validation
422 Unprocessable Entity
{
  "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

One handler for the whole API
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.

FieldTypeDescription
detail
string, array or objectWhat 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.

FieldTypeDescription
detail
objectWhy 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
stringA sentence describing the refusal.
detail.retryAfterSeconds
integerSeconds to wait before retrying; equals the Retry-After header.
detail.queueDepth
integer or nullSearches 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 nullThe 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 stringRegistries that did not finish, when the search ran, found no records and could not complete because the service was at capacity.
detail.sourcesQueried
integerRegistries 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.

HeaderMeaning
Retry-AfterOn 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.

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.

Product overview