- Docs
- API reference
- Endpoints and schemas
- KYB API
Errors and rate limits
The status codes the KYB API returns, what each means, and which requests are safe to retry.
The KYB API reports a failed request through its HTTP status and, usually, a
JSON error body. Use the status to decide, for each response, whether to fix
the request, retry it, or read the result. This page covers both
endpoints: POST /v2/kyb/
and GET /v2/kyb/{task_id}.
A 200 means Enigma processed the request. It does not mean any task
succeeded. A request with no match, or one where every task failed, still
returns 200. Read the outcome from data and each task’s result. See
How checks work for every result.
Error body
Section titled “Error body”Errors from the KYB API return a JSON object with error, message and, on
some responses, details. One example comes from validation, and one carries
details:
{ "error": true, "message": "Bad Request: TIN Verification is not supported for top_n > 1"}{ "error": true, "message": "An error occurred while processing your request", "details": "Internal Server Error. Contact support."}errorAlways
true.messageWhat went wrong. Validation errors start with
Bad Request:. Use it to debug and to log. The wording can change, so do not match on it.detailsOn some 400 and 500 responsesOn a
400with the generic messageAn error occurred while processing your request,detailsholds the cause. On a500,detailsis a fixed support message.
Not every error has this body. Errors from the gateway in front of the KYB
API, and from its rate limiter, can return a different JSON body. Examples are
some authentication failures, unknown paths, some rate-limit responses and
gateway timeouts. Some 500 responses return an empty object ({}). Branch on
the HTTP status first, and read message only when it is present.
Error responses do not include a response_id. When you contact
Enigma support about an error, give the
endpoint, the time of the request and the status.
Status codes
Section titled “Status codes”Each row gives the status, what it means, and what to do next. How to time a retry is in Retries and backoff.
200Do not retryThe request was processed. This includes no match and failed tasks. A few task results call for a retry; see Retry after a 200.
400Fix the requestThe request failed validation. The
messagefield names the first failed rule; see Common 400 messages.401Check the keyThe
x-api-keyheader is missing, or the API key is invalid. Do not retry unchanged.403Check the key, method and pathAccess was denied, or the method and path do not exist, for example
GET /v2/kyb/. Do not retry unchanged.404Check the task IDGET /v2/kyb/{task_id}only. The task ID is not valid, is unknown, or belongs to another organization. Do not retry. Check that you passedbackground_task.idfrom a POST request sent by your organization.429Retry after the waitToo many requests. Retry after the
Retry-Afterwait or with backoff. See Rate limits.500Fix the request, or retryAn unexpected error. A
top_nthat is not a whole number, or an address value that is not a string, can cause it: fix the request first in that case. Otherwise retry with backoff, and contact Enigma support if it persists.502Retry with backoffA data service that Enigma depends on failed or could not be reached.
503Retry with backoffGET /v2/kyb/{task_id}only. Enigma cannot look up background tasks right now. Your background task can still exist.504Retry with backoffNo response within about 29 seconds. Enigma can still finish the request. See Timeouts.
Any other 4xx status is rare. Do not retry it unchanged; contact Enigma
support.
Common 400 messages
Section titled “Common 400 messages”Enigma validates the request before it searches, and returns the first rule
that fails. Fix it and resend: another rule can fail next. The messages below
are the text that follows Bad Request:, for debugging only. Text in angle
brackets varies. tin and tins together are rejected only when you request
tin_verification. The rules themselves are in
Validation.
| Cause | Message |
|---|---|
Body is not JSON, or Content-Type: application/json is missing |
Invalid JSON in request body: <detail> |
data is sent with other top-level keys |
If 'data' in Request body, all fields must be nested under 'data' |
| No business name | Provide at least one business name (primary_name or name or names) |
Both name and names |
Request cannot contain both 'name' and 'names' fields |
A field and its plural, such as address and addresses |
Request must only include '<field>' or '<other field>', not both. |
Both primary_name and name |
Request must only include '<field>' or '<other field>', not both. |
| Too many values | Provide up to two business namesProvide up to two address objectsProvide up to one websiteProvide up to one person |
| A field has the wrong type | '<field>' is type '<actual>' but must be a '<expected>' |
Unknown key in person |
Invalid keys for person object: <keys> | Valid keys: first_name, last_name, date_of_birth, address, ssn |
package is not identify or verify |
Available packages are "identify" and "verify". To request attributes for matched entities only, use the "products" parameter instead. |
package with products |
Query parameters 'package' and 'products' are mutually exclusive |
attrs with products |
Query parameters 'attrs' and 'products' are mutually exclusive; list the attributes you want in 'products' |
products is empty |
Query parameter 'products' must list at least one attribute |
products has an unknown value |
Unknown attribute(s) in 'products': <values> |
card_transactions on its own |
Include specific card_transaction types in 'attrs' to get card_transactions in the response. <allowed values> |
top_n is below 1 |
Query parameter 'top_n' must be greater than 0 |
match_threshold is not a number from 0 to 1 |
Query parameter 'match_threshold' must be a floatQuery parameter 'match_threshold' must be between 0 and 1 |
Person-only screen where attrs is not exactly watchlist |
When only a person object is provided, attrs must be exactly 'watchlist' |
tin_verification or ssn_verification with top_n above 1 |
TIN Verification is not supported for top_n > 1SSN Verification is not supported for top_n > 1 |
TIN is missing or malformed, with tin_verification |
Must provide a TIN for Tin VerificationProvide a 9-digit string for EIN/TIN screeningThe 'tins' field must be a list of 1 to 2 TINs in double quotes. |
tin_verification with a TIN but no business name |
Provide at least one business name for EIN/TIN verification |
Person or SSN is missing or malformed, with ssn_verification |
Must provide a person object for SSN VerificationMust provide an SSN for SSN VerificationThe SSN for SSN Verification must be provided on the person objectProvide a 9-digit string for SSN screening |
Rate limits
Section titled “Rate limits”KYB API rate limits depend on your plan and contract. Contact Enigma support to confirm the limits for your account.
When you exceed a limit, the API returns 429. A 429 response can include a
Retry-After header with the number of seconds to wait, and not every 429
uses the standard error body. Handle both cases:
- If
Retry-Afteris present, wait at least that many seconds before you retry. - Otherwise, back off as described in Retries and backoff.
- If you still get
429after several retries, slow your request rate before you continue.
Retries and backoff
Section titled “Retries and backoff”Retry 429, 500 (after you rule out the input causes in
Status codes), 502, 503 and 504 with exponential
backoff: start at 1 second and double the wait on each retry (1, 2, 4, 8
seconds, and so on), up to 60 seconds. Set a maximum number of
attempts, and add a small random delay so that parallel clients do not retry
in step.
Wait at least 60 seconds before you resend a request that includes
tin_verification or ssn_verification. The IRS rejects the same TIN or SSN
submitted again within a short window, and the task result is then
duplicate. This applies after a 504 too, because the first request may
have reached the IRS.
Retry after a 200
Section titled “Retry after a 200”Some task results in a 200 response mean a check did not complete. They
mean the check did not finish, not that it found nothing.
| In the response | Meaning | What to do |
|---|---|---|
watchlist is not_completed |
Watchlist screening did not complete and found no hits. watchlists can hold a string instead of hit objects. |
Retry the request. Do not treat it as no hits. |
tin_verification or ssn_verification is not_completed |
The IRS was unavailable, or no verification result came back. | Retry after 1 minute, then 2, then 4, up to 30 minutes between retries. See When the IRS is unavailable. |
tin_verification or ssn_verification is duplicate |
The same TIN or SSN was submitted again within a short window. | Resend after the 60-second wait in Retries and backoff. |
background_task.status is failed and id is null |
The background task for negative news could not be created. The rest of the response is complete. | Resend the request to get negative news. |
background_task is missing |
You requested negative_news and a registered entity matched, but negative news did not run. |
Resend the request. Do not treat it as no negative news. |
A pending background task is not an error. Poll it with the backoff in
Poll for results.
Timeouts
Section titled “Timeouts”A request has one time limit as a whole, and two checks deliver results that can be partial or late.
| Limit | Behavior | What to do |
|---|---|---|
| Whole request | The gateway returns 504 if the request takes longer than about 29 seconds. Enigma can still finish the request, but you do not receive that response. |
Set your client timeout to about 30 seconds. A longer timeout gains nothing. |
| Watchlist screening | Screening has a time budget. When it runs out, the request still returns 200. The watchlist task is not_completed if no hits were found, or watchlist_hits if some were, and more hits can exist. |
The hit list can be partial. See Retry after a 200 and When screening does not complete. |
| Negative news | Articles that are not ready when the POST returns arrive through a background task. | Poll GET /v2/kyb/{task_id}. |
Related
Section titled “Related”POST /v2/kyb/: parameters, body fields and validation rules.GET /v2/kyb/{task_id}: polling a background task.- How checks work: every task and its results.
- Watchlist screening and Negative news: the checks with partial and delayed results.
- Response object: the fields of a
200response.