Errors & Retries

Canonical v1 API error model, retry playbook, and endpoint-by-endpoint error matrix for production integrations.

API Reference Endpoint Catalog OpenAPI v1 JSON

Error envelope

All endpoints return JSON. Errors use the envelope below; fields may include additional context per endpoint.

{
  "ok": false,
  "error": "rate_limited",
  "message": "Too many requests. Limit is ~10 rps."
}

HTTP status guide

Status	Meaning	Action
400	Request shape/inputs invalid	Fix payload/query and retry once corrected.
401	Missing or invalid credentials	Refresh key/secret, then retry.
403	Authenticated but not allowed	Check tenant scope or plan entitlements.
404	Resource not found	Verify IDs and tenant ownership before retry.
409	Conflict / duplicate operation	Treat as non-retriable unless state changes.
429	Rate or monthly usage limit reached	Backoff with jitter and retry later.
500	Unexpected server failure	Retry with backoff; alert if persistent.
501	Feature not supported on endpoint	Use supported type/route from docs.
503	Temporary dependency or meter outage	Retry with exponential backoff.

Retry policy

Retry: 429, 500, 503.
Do not blind-retry: 400, 401, 403, 404, 409, 501.
For POST requests, send Idempotency-Key where supported.
Backoff recommendation: 1s, 2s, 4s, 8s, cap at 30s, with jitter.

Endpoint error matrix (complete /api/v1)

The table below covers all public customer-facing v1 paths. For request and response schemas, see Endpoint Catalog and OpenAPI v1.

Internal operational routes are documented in Dashboard Docs only.

Endpoint	Methods	Typical errors
/api/v1/ping	GET	401 invalid_api_key, 429 rate_limited, 503 usage_meter_error
/api/v1/screen	POST	400 bad_request\|no_names\|too_many_names, 401 unauthorized, 429 rate_limited\|limit_exceeded, 500 engine_error
/api/v1/cross-border-risk	POST	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 server_error
/api/v1/usage/summary	GET	400 missing_tenant, 401 unauthorized, 403 forbidden_tenant, 500 not_configured\|server_error
/api/v1/datasets	GET	401 invalid_api_key, 403 tier access restrictions, 429 rate_limited, 500 server_error
/api/v1/settings	GET, PUT	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 server_error
/api/v1/analytics	GET	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/audit/list	GET	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/billing/summary	GET	401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/billing/usage	GET	401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/cases	GET, POST	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/cases/[id]	GET, PATCH	400 bad_request, 401 invalid_api_key, 404 not_found, 500 db_error\|server_error
/api/v1/cases/analytics	GET	401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/cases/status-by-audit	POST	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/export	GET	400 unsupported_type\|missing params, 401 invalid_api_key, 404 not_found, 501 not_supported, 500 internal_error
/api/v1/ownership/check	GET	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 server_error
/api/v1/keys	GET, POST, DELETE	400 bad_request, 401 invalid_api_key, 403 entitlement_forbidden, 404 not_found, 500 server_error
/api/v1/keys/[id]/revoke	POST, DELETE	400 missing_key_id, 401 invalid_api_key, 500 update_failed\|server_error
/api/v1/team	GET, POST	400 invalid_team payload, 401 invalid_api_key, 403 forbidden, 409 conflict, 500 server_error
/api/v1/team/[teamId]/members	GET, PUT, DELETE	400 invalid_team_id\|bad_request, 401 invalid_api_key, 403 forbidden, 404 team_not_found\|user_not_found, 500 server_error
/api/v1/directory/teams	GET	401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/directory/entities	GET, POST, PATCH, DELETE	400 bad_request, 401 invalid_api_key, 403 forbidden, 404 not_found, 500 db_error\|server_error
/api/v1/directory/rescreen	POST	400 bad_request, 401 invalid_api_key, 404 entity_not_found, 429 rate_limited, 500 engine_error\|server_error
/api/v1/rescreen/cohorts	GET, POST, DELETE	400 bad_request, 401 invalid_api_key, 404 not_found, 429 rate_limited, 500 db_error\|server_error
/api/v1/rescreen/jobs	GET, POST, PATCH, DELETE	400 bad_request, 401 invalid_api_key, 403 forbidden, 404 not_found, 429 rate_limited, 500 db_error\|server_error
/api/v1/rescreen/runs	GET, POST	400 bad_request, 401 invalid_api_key, 404 not_found, 429 rate_limited, 500 db_error\|server_error
/api/v1/webhooks/endpoints	GET, POST, PATCH, DELETE	400 bad_request, 401 unauthorized, 404 not_found, 409 conflict, 500 server_error
/api/v1/webhooks/deliveries	GET	400 bad_request, 401 unauthorized, 500 server_error
/api/v1/webhooks/test-fire	GET, POST	400 bad_request, 401 unauthorized, 404 endpoint_not_found, 500 server_error

HTTP status guide

Status	Meaning	Action
400	Request shape/inputs invalid	Fix payload/query and retry once corrected.
401	Missing or invalid credentials	Refresh key/secret, then retry.
403	Authenticated but not allowed	Check tenant scope or plan entitlements.
404	Resource not found	Verify IDs and tenant ownership before retry.
409	Conflict / duplicate operation	Treat as non-retriable unless state changes.
429	Rate or monthly usage limit reached	Backoff with jitter and retry later.
500	Unexpected server failure	Retry with backoff; alert if persistent.
501	Feature not supported on endpoint	Use supported type/route from docs.
503	Temporary dependency or meter outage	Retry with exponential backoff.

Endpoint error matrix (complete /api/v1)

The table below covers all public customer-facing v1 paths. For request and response schemas, see Endpoint Catalog and OpenAPI v1.

Internal operational routes are documented in Dashboard Docs only.

Endpoint	Methods	Typical errors
/api/v1/ping	GET	401 invalid_api_key, 429 rate_limited, 503 usage_meter_error
/api/v1/screen	POST	400 bad_request\|no_names\|too_many_names, 401 unauthorized, 429 rate_limited\|limit_exceeded, 500 engine_error
/api/v1/cross-border-risk	POST	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 server_error
/api/v1/usage/summary	GET	400 missing_tenant, 401 unauthorized, 403 forbidden_tenant, 500 not_configured\|server_error
/api/v1/datasets	GET	401 invalid_api_key, 403 tier access restrictions, 429 rate_limited, 500 server_error
/api/v1/settings	GET, PUT	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 server_error
/api/v1/analytics	GET	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/audit/list	GET	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/billing/summary	GET	401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/billing/usage	GET	401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/cases	GET, POST	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/cases/[id]	GET, PATCH	400 bad_request, 401 invalid_api_key, 404 not_found, 500 db_error\|server_error
/api/v1/cases/analytics	GET	401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/cases/status-by-audit	POST	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/export	GET	400 unsupported_type\|missing params, 401 invalid_api_key, 404 not_found, 501 not_supported, 500 internal_error
/api/v1/ownership/check	GET	400 bad_request, 401 invalid_api_key, 429 rate_limited, 500 server_error
/api/v1/keys	GET, POST, DELETE	400 bad_request, 401 invalid_api_key, 403 entitlement_forbidden, 404 not_found, 500 server_error
/api/v1/keys/[id]/revoke	POST, DELETE	400 missing_key_id, 401 invalid_api_key, 500 update_failed\|server_error
/api/v1/team	GET, POST	400 invalid_team payload, 401 invalid_api_key, 403 forbidden, 409 conflict, 500 server_error
/api/v1/team/[teamId]/members	GET, PUT, DELETE	400 invalid_team_id\|bad_request, 401 invalid_api_key, 403 forbidden, 404 team_not_found\|user_not_found, 500 server_error
/api/v1/directory/teams	GET	401 invalid_api_key, 429 rate_limited, 500 db_error\|server_error
/api/v1/directory/entities	GET, POST, PATCH, DELETE	400 bad_request, 401 invalid_api_key, 403 forbidden, 404 not_found, 500 db_error\|server_error
/api/v1/directory/rescreen	POST	400 bad_request, 401 invalid_api_key, 404 entity_not_found, 429 rate_limited, 500 engine_error\|server_error
/api/v1/rescreen/cohorts	GET, POST, DELETE	400 bad_request, 401 invalid_api_key, 404 not_found, 429 rate_limited, 500 db_error\|server_error
/api/v1/rescreen/jobs	GET, POST, PATCH, DELETE	400 bad_request, 401 invalid_api_key, 403 forbidden, 404 not_found, 429 rate_limited, 500 db_error\|server_error
/api/v1/rescreen/runs	GET, POST	400 bad_request, 401 invalid_api_key, 404 not_found, 429 rate_limited, 500 db_error\|server_error
/api/v1/webhooks/endpoints	GET, POST, PATCH, DELETE	400 bad_request, 401 unauthorized, 404 not_found, 409 conflict, 500 server_error
/api/v1/webhooks/deliveries	GET	400 bad_request, 401 unauthorized, 500 server_error
/api/v1/webhooks/test-fire	GET, POST	400 bad_request, 401 unauthorized, 404 endpoint_not_found, 500 server_error