Errors, rate limits, and safe retries

Errors use an error object with code, message, and requestId. Validation errors can add field details. Store the code and request ID for support without copying subject inputs into logs. An HTTP error must never become a no_match result in your application.

400 usually requires correcting a request. 401 and 403 require authentication or permission repair. 409 can indicate an idempotency conflict or an unavailable upload. 410 means retained evidence expired. A 503 can mean missing service configuration or unavailable production capability.

The API currently enforces 120 authenticated requests per minute per key or human actor through durable database counters. A rate_limited error uses 429. Wait with bounded exponential backoff and jitter before retrying; do not launch more concurrent clients to evade the limit.

usage_cap_reached also uses 429, but time-based backoff alone may not solve it. Check plan allowance, reserved work, and the configured subject cap. Failed screens do not count as completed subjects, while completed batch rows and monitoring rescreens do. No automatic excess charge is created.

For uncertain network or server failures, reuse the same screening or batch Idempotency-Key and identical input. Stop after a bounded retry budget and surface the failure. If required coverage is unavailable or candidate retrieval exceeds its safe bound, escalate the incomplete check rather than silently selecting fewer sources or dropping candidates.