Errors

Errors are RFC 7807 problem details.

Every error response is a machine-readable application/problem+json body with a matching HTTP status. Read status and detail; branch on the status code.

The problem shape

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Monthly screening quota exceeded (50000/50000)."
}

Validation failures (400) include a errors map keyed by field name, so you can surface field-level messages directly.

Status-code map

Status	Meaning	What to do
`200` / `201`	Success. `201` on resource creation (screen, tenant).	Proceed; read the body.
`204`	Success, no content (e.g. key revoked).	Proceed.
`400`	Validation error — bad/missing field.	Read `errors`; fix the request. Do not retry unchanged.
`401`	Missing or invalid credential (bad token / unknown API key).	Re-authenticate; check the token audience & expiry.
`403`	Authenticated but not authorized — wrong role, or credential not tenant-scoped.	Use a credential with the required policy/role.
`404`	Resource not found, or not visible to your tenant.	Check the id; remember resources are tenant-scoped.
`429`	Monthly screening quota exceeded.	Back off; raise the quota (admin) or wait for the month to roll over.
`500`	Unexpected server error.	Retry with backoff; quote the correlation id if it persists.

Correlation IDs

Every request is tagged with a correlation id (echoed in responses and structured logs). When you report an issue, include it so the problem can be traced end-to-end.

Retry guidance

Safe to retry: 429 (after backoff), 500/transient network errors.
Do not retry unchanged: 400, 401, 403, 404 — fix the request or credential first.
Idempotency: pass an Idempotency-Key on POST /v1/screenings/check so a retried screen returns the original result instead of re-screening (and re-billing).

← Webhooks Next: Quota & limits →