Find the next step for an error
Match the exact error.code, then check the operation’s contract. A failed or uncertain request is never a no-match result. Unknown codes need investigation with the request ID. This table covers common recovery decisions; search documentation for other documented codes and their endpoint-specific response instructions.
| Code / status | Meaning and next action | Retry and request key |
|---|---|---|
invalid_request400 / 408 / 413 / 415 | A request field, body, size, read deadline or media type was rejected. Next: Read error.message and error.details. Correct the fields, body size or media type, or resolve an interrupted body upload. | Retry: After correcting the request. Key: Use a new operation key for changed input. |
idempotency_key_required400 | The operation requires a valid request identity. Next: Persist a unique 8–128 character URL-safe key with the intended request before sending it. | Retry: After providing a valid key. Key: Reuse this key and identical body for this operation. |
authentication_required401 | The request did not supply an accepted credential. Next: Send Authorization: Bearer with a server-side key for the intended environment. | Retry: After fixing authentication; no repeated automatic retries. Key: Keep the original operation key and body. |
invalid_api_key401 | The supplied API key is invalid, expired or revoked. Next: Check the configured key. Ask an authorized administrator for a replacement when needed. | Retry: After fixing the credential. Key: Credential replacement does not create a new operation. |
subscription_required402 | Production access has not been established. Next: Check your live access and remaining allowance in Billing. Ask the billing contact for help. Optional sandbox tests use a separate allowance. | Retry: After your workspace has live access and a free or paid allowance. Key: Keep the original operation key and requested coverage. |
idempotency_conflict409 | This key already identifies a different request or operation. Next: Compare the stored endpoint and input. Recover the original operation before deciding whether a new one is intended. | Retry: Do not retry conflicting input unchanged. Key: A new key is only for a deliberate new operation. |
stale_revision409 | The saved resource changed after it was read. Next: Reload the resource, compare the changes and reconsider the intended update. | Retry: After reconciliation with the current revision. Key: Use a new key for the revised update. |
monitor_changed409 | The monitor no longer matches the expected state. Next: Reload the monitor and reconcile its current identity, coverage and revision. | Retry: After reviewing the changed state. Key: Use a new key for a changed operation. |
counterparty_changed409 | The saved customer or vendor record changed. Next: Read its current identity and revision; resolve the difference in the dashboard before linking new work. | Retry: After the identity and revision agree. Key: Changed input needs a new operation key. |
upload_unavailable409 | An upload may be pending, invalid, expired or already used. Next: If completion is still pending, wait within a bounded deadline. Otherwise investigate the upload before allocating another. | Retry: Only pending completion may recover with a bounded delay. Key: Keep the same batch key and upload ID during pending completion. |
case_exists409 | A case already exists for this screening. Next: Use error.details.caseId or read GET /cases?screeningId=ID to find it. | Retry: Read the existing case; do not create it again. Key: POST /cases has no Idempotency-Key contract. |
result_expired410 | The retained screening evidence is no longer available. Next: Preserve the evidence gap. When appropriate, create a new screening and link it as a replacement. | Retry: The expired result cannot be recovered by retrying. Key: A replacement screening is a new operation with a new key. |
response_too_large413 | The requested response exceeds the response-size limit. Next: Reduce the page size or report range and follow every continuation returned. | Retry: After narrowing the read request. Key: Reads do not need a new screening key. |
investigation_too_large413 | The retained case exceeds the bounded response size. Next: Retrieve the complete segmented case archive, preserving its revision and all segments. | Retry: Use the archive endpoint instead. Key: An export does not create a new screening operation. |
standard_retention_required422 | The workflow requires retained evidence for review or governance. Next: Use standard retention and preserve the approved policy requirements. | Retry: After deliberately correcting retention. Key: Changed input needs a new operation key. |
rate_limited429 | The request or credential-verification rate is too high. Next: Honor Retry-After, use bounded backoff with jitter and reduce concurrent requests. | Retry: Yes, within a capped retry budget. Key: Keep the same key and identical body for idempotent writes. |
usage_cap_reached429 | Completed and reserved work has exhausted the available allowance. Next: Read usage, reservations and the organization subject cap. Wait for capacity or ask the billing contact to resolve it. | Retry: Only after allowance or reservations change; backoff alone may not help. Key: Keep the original key. Additional API keys do not increase allowance. |
temporarily_unavailable503 | The service or required screening capacity is temporarily unavailable. Next: Honor Retry-After and retry within a bounded budget. Keep required coverage unchanged; use requestId for support. | Retry: Yes, when the endpoint permits safe recovery. Key: Preserve the same key and body for idempotent writes; reconcile other POST operations first. |
invalid_coverage422 | The requested source IDs or package do not form valid coverage. Next: Read source discovery in the same environment. Correct the selector without silently removing required sources. | Retry: After a deliberate correction to the approved scope. Key: Changed coverage is changed input and needs a new operation key. |
coverage_unavailable503 | Required coverage is currently unavailable for the request. Next: Inspect current source availability and keep the required scope. Resolve eligibility or availability before resuming. | Retry: After required sources become available; repeated retries alone do not qualify a source. Key: Preserve the same key and body when recovering this operation. |
stale_coverage503 | Required source data is outside the allowed freshness policy. Next: Check source version timestamps and freshness. Wait for a successful refresh or escalate the data gap. | Retry: After freshness is restored. Do not treat stale data as a completed current check. Key: Preserve the original key, input and required sources. |
production_screening_disabled503 | The service is not accepting production screenings. Next: Check service status or contact support with the request ID. Keep sandbox testing separate from production evidence. | Retry: After production screening is enabled; do not retry indefinitely. Key: Keep the original key and body for the intended production operation. |
Timeout / connection failureNo reliable response | A timeout, lost connection or unreadable response leaves completion uncertain. Next: Recover the original idempotent operation. For case creation, upload intents and webhook registration, reconcile using the endpoint-specific instructions. | Retry: Only with the endpoint’s recovery contract. Key: Never generate a fresh key just because the response was lost. |
For an unavailable source, preserve the required scope and resolve eligibility or obtain a deliberate approved coverage change. Do not silently remove sources. See idempotency contracts and source availability.
Use the error code and request ID
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 requires correcting request fields or JSON. 401 and 403 require authentication or permission repair. 404 means the resource or exact path is unavailable; 405 includes an Allow header listing supported methods. 408 means the JSON body exceeded its ten-second deadline. A 413 means the request or response exceeded its size limit; inspect the error code before changing input. A 415 requires uncompressed application/json with UTF-8 encoding. 409 can indicate an idempotency conflict or an unavailable upload; 410 means retained evidence expired. A 503 means the service or selected screening coverage is currently unavailable; use its documented public code and retry guidance.
Every v1 response includes X-Request-Id. Error bodies repeat that ID. Field diagnostics contain at most 50 bounded issues; detailsTruncated is true if additional issues were omitted. Unknown fields, duplicate object keys, excessive nesting and repeated or unsupported query parameters are rejected.
Nonstreamed responses and case archive segments have a 3 MiB serialized limit. Lists can return fewer complete items and a continuation; follow it until absent. For response_too_large, narrow a report range or reduce the page limit. For investigation_too_large, export the retained case through its complete segmented archive. Potential matches are never silently removed to make a response fit.
Handle one stable error envelope
Authenticated application errors always have an error object with code (string), message (string), and requestId (string). data is absent on this error path. For client and validation failures, details is optional and can be a validation-issue array or endpoint-specific diagnostic object. detailsTruncated is optional and appears when validation issues were omitted. Server failures do not return details. Do not require details or assume it is always an array.
This synthetic example shows the shape of a field-validation failure. Match on code and HTTP status rather than human message text. Treat details[].path as a form-field path when details is an array. On successful JSON calls the envelope is data; X-Request-Id is the consistent header for support correlation and is not a guaranteed success-body key.
A reverse proxy or failed network connection may provide no parseable API response at all. Keep that as an uncertain transport failure. The request helper handles non-JSON failures without fabricating a screening result.
{
"error": {
"code": "invalid_request",
"message": "The request is invalid.",
"requestId": "00000000-0000-4000-8000-000000000001",
"details": [
{
"path": "subject.name",
"message": "Too small: expected string to have >=2 characters"
}
]
}
}Choose recovery by cause, not just status
Retry only when the same request can reasonably succeed: rate_limited (429), temporary transport failures, and transient capacity/server failures. Honor Retry-After when present, use exponential backoff with jitter, cap both attempts and elapsed time, and preserve the operation’s idempotency key and body. Unexpected 5xx responses can represent an uncertain commit.
Retry-After can be a delay in seconds or an HTTP-date. For a date, calculate the remaining delay against your current clock and never use a negative delay. A service-unavailable response uses a one-second delay by default; your bounded backoff can wait longer. If the header is absent, use your retry policy rather than assuming immediate recovery.
Do not automatically retry unchanged 400/401/403/404/405/410/415/422 errors. Correct JSON, credentials, authorization, path, media type or workflow requirements first. A 402 subscription_required needs production entitlement. usage_cap_reached (429) needs allowance or reservations to change; creating parallel keys does not create more subject allowance.
For 409 idempotency_conflict, compare your operation record before creating anything new. For revision conflicts such as monitor_changed or counterparty_changed, reread and reconcile current state. For upload_unavailable, distinguish pending completion from invalid/expired/already-used input. For coverage failures, restore the required source eligibility or ask the responsible reviewer to choose a new approved scope; never silently screen a smaller set.
The linked endpoint reference for each workflow lists endpoint-specific HTTP statuses and examples. Unknown future error codes should produce a visible recoverable failure with request ID, not a successful business decision. Keep subject payloads, API keys, document links and complete error bodies out of routine logs.
Distinguish two kinds of limit
The API currently enforces 120 authenticated requests per minute per key or human actor. 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.
Bursts of uncached API-key verification have a separate rate limit and can also return 429 rate_limited. Applications sharing an outbound IP address share that verification budget. Honor Retry-After, reuse valid credentials and avoid repeatedly retrying an invalid key.
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.
Recover without changing the question
A temporary service failure returns 503 temporarily_unavailable with a generic message and request ID. Honor Retry-After and use bounded exponential backoff with jitter. A timeout is an uncertain outcome until an idempotent retry recovers it.
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.
Frequently asked questions
How do I tell a rate limit from a screening usage cap?
Read error.code. rate_limited means requests are arriving too quickly; follow Retry-After and reduce concurrency. usage_cap_reached means completed and reserved work has reached the allowance. Inspect usage and reservations before retrying; backoff alone may not create capacity.
Can I treat coverage_unavailable as an empty match list?
No. The required source selection was not available for the request. Keep the check incomplete, inspect source availability, and preserve the required scope. Removing a required source or turning the error into no_match would change what was checked.
What should I send support when an API call fails?
Send the public error code and request ID, with a description of the operation and relevant client version. Keep API keys, subject inputs, and raw evidence out of the message and routine logs. Every v1 response provides X-Request-Id.
What should I change after response_too_large?
Reduce the page size or report range and follow all returned continuations. A short page can still have more results. For investigation_too_large, use the segmented case archive. The service does not silently remove potential matches to fit a response.
KEEP BUILDING