Errors, status codes & rate limits

Status codes

The API uses conventional HTTP status codes. Note that a 200 can still carry a partial result: when you set a deadlineMs bound, the sources that completed within it are returned and every source is labelled in sourceStatus, rather than failing the whole call. Billing must be enabled on an account before the API returns live results.

The error envelope

Every non-2xx response returns a JSON body with a stable error.code you can switch on and a human-readable error.message you can surface to a user. The shape is identical on every endpoint, so one error handler covers the whole API.

{
  "error": {
    "code": "invalid_request",
    "message": "query requires at least one of lastName, q, or a lat/lng radius."
  }
}

{
  "error": {
    "code": "unprocessable_query",
    "message": "A firstName on its own cannot be answered completely. Pair it with a lastName, a dob, or an age."
  }
}

Switching on the code

const res = await fetch(url, { method: "POST", headers, body });

if (!res.ok) {
  const { error } = await res.json();
  switch (res.status) {
    case 401: throw new Error("Check X-API-Key: " + error.message);
    case 402: throw new Error("Billing is not enabled on this account.");
    case 422: return { declined: error.message };          // show the user
    case 429: return retryAfter(res.headers.get("Retry-After"));
    default:  throw new Error(`${error.code}: ${error.message}`);
  }
}

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
}

Rate limits & quotas

Requests are rate limited per API key. When you exceed your plan’s sustained rate or monthly quota the API responds with 429 Too Many Requests and a Retry-After header (seconds) telling you when to try again. Every response also carries the current limit state, so you can throttle proactively rather than discovering the ceiling on a rejection.

Concurrency and monthly volume are set by your plan. For large jobs, prefer the asynchronous endpoint or batch and spread submissions, rather than issuing thousands of synchronous calls at once. Contact us to raise your limits. 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 send an Idempotency-Key header and a repeated key returns the original job rather than creating a new one, which makes a dropped-connection retry 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.