Errors & status codes

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; message may be reworded.

{
  "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

There is no request rate limit today. No endpoint returns 429, and no Retry-After header is emitted. Apply your own client-side concurrency control — a cached search over a common surname can return up to 200 records per page and many pages.

Two errors, verbatim

{
  "error": {
    "code": "unauthenticated",
    "message": "the X-API-Key header is missing or malformed"
  }
}

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