Error handling

import time, requests

API, KEY = "https://sandbox.offendersearch.app", "os_test_your_key"
RETRY_STATUSES = {429, 502, 503, 504}

class Refused(Exception):
    def __init__(self, status, code, message): super().__init__(f"{status} {code}: {message}"); self.code = code

def criminal(method, path, attempts=4, **kw):
    for n in range(attempts):
        r = requests.request(method, API + path, headers={"X-API-Key": KEY}, timeout=90, **kw)
        if r.ok:
            return r
        if r.status_code in RETRY_STATUSES:                 # nothing was searched, nothing billed
            wait = float(r.headers.get("Retry-After") or min(2 ** n, 30))
            if r.status_code == 503:
                try: code = r.json()["error"]["code"]       # retry | filters_unavailable | unavailable | catalog_unavailable
                except Exception: code = "?"
                if code == "filters_unavailable":            # Retry-After: 300 — or resend without filters
                    raise Refused(503, code, r.json()["error"]["message"])
            time.sleep(wait); continue
        if r.status_code in (401, 402):
            raise Refused(r.status_code, "gateway", r.json()["detail"])
        body = r.json()                                     # 400 / 404 / 413 / 422: fix the request
        raise Refused(r.status_code, body["error"]["code"], body["error"]["message"])
    raise TimeoutError("still failing after retries; keep the request and try later")

for body in ({"query": {"firstName": "Felony"}},                                   # guard_unbounded_query
             {"query": {"lastName": "Record", "firstName": "Felony", "dob": "06/15/1975"}},  # invalid_dob
             {"query": {"lastName": "Record"}, "perPage": 300},                   # invalid_page
             {"query": {"lastName": "Record", "state": "OH"}, "locations": [{"state": "OH"}]},  # ambiguous_location
             {"query": {"lastName": "Record"}, "filters": {"severity": ["capital"]}},  # invalid_filter_value
             {"query": {"lastName": "Record"}, "live": True}):                    # invalid_live
    try:
        criminal("POST", "/v1/criminal/search", json=body)
    except Refused as e:
        print(e)

// 422 from the criminal service — branch on error.code
{ "error": { "code": "guard_unbounded_query", "message": "a lastName predicate is required — an unbounded query returns a lottery, not an answer" } }
{ "error": { "code": "invalid_dob", "message": "dob must be a date in 'YYYY-MM-DD' form" } }
{ "error": { "code": "invalid_page", "message": "perPage must be from 1 to 200 (got 300)" } }
{ "error": { "code": "invalid_filter_value", "message": "filters.severity: capital not allowed; use one of felony, misdemeanor, infraction" } }
{ "error": { "code": "invalid_live", "message": "live must be a JSON object, not a JSON boolean" } }
{ "error": { "code": "query_too_broad", "message": "This query is too broad to be answered completely: …" }, "detail": "This query is too broad to be answered completely: …" }

// 401 / 402 from the gateway — one sentence in detail
{ "detail": "Provide a valid X-API-Key or session token." }
{ "detail": "No active subscription for this account. Start a subscription (POST /v1/billing/checkout-session) or update your payment method (POST /v1/billing/portal-session) to use the API." }

// 503 / 504 — nothing was searched; resend the same request
{ "error": { "code": "retry", "message": "Criminal Search could not run this search just now, so NOTHING was searched and no result is implied. Retry the same request — it is expected to succeed." } }
{ "error": { "code": "upstream_timeout", "message": "Criminal Search took too long to respond, so NOTHING was returned and no result is implied. Retry the same request." } }