Errors
Every status code and error code the API returns, and what to do about each one.
Every error is JSON with a machine-readable code and a human-readable message. Branch on code, not on message — messages are written for people and may change.
{ "code": "rate_limited", "message": "Rate limit exceeded. Retry after 12 seconds." }Status codes
| Status | code | Meaning | What to do |
|---|---|---|---|
400 | invalid_request | The body or a parameter is invalid. fields names each invalid field and why. | Fix the named fields. Retrying the same request will fail the same way. |
401 | unauthorized | The API key is missing, malformed or revoked. | Check the Authorization header; rotate the key if it was revoked. |
402 | api_allowance_reached | The organization has used its monthly API allowance on a plan that does not bill the excess. The body's block names the reset date and the plans with more room. | Wait for the reset date or change plan. Nothing was charged. |
402 | single_screening_allowance_reached | The monthly screening allowance is used up. | Same as above. |
403 | forbidden | The organization is read-only: a trial has ended or a payment is overdue. Reads (/lists, /usage) still work. | Choose a plan or settle the payment in the app. |
404 | not_found | The batch job or monitored record does not exist for this key's organization. | Check the id. A second DELETE of the same monitored record is also a 404. |
429 | rate_limited | The per-key burst limit was exceeded. | Wait the number of seconds in Retry-After. Retrying earlier still counts against the window. |
5xx | — | Something failed on our side. | Retry with exponential backoff, reusing the same Idempotency-Key. |
Validation errors
A 400 carries the field-level detail so the fix is in the response:
{
"code": "invalid_request",
"message": "Invalid request.",
"fields": { "dateOfBirth": ["dateOfBirth must be YYYY-MM-DD."] }
}Retrying safely
Send an Idempotency-Key header on POST /screen (optional) and POST /batch (required). A retry with the same key is not metered twice, and a resubmitted batch returns the job you already have. Use a value that identifies the operation in your system — a record id plus a date, for example — not a fresh random value per attempt.