Skip to content
Console(opens in a new tab)

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.

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:

400 Bad Request
{
"error": true,
"message": "Bad Request: TIN Verification is not supported for top_n > 1"
}
errorboolean

Always true.

messagestring

What 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.

detailsstringOn some 400 and 500 responses

On a 400 with the generic message An error occurred while processing your request, details holds the cause. On a 500, details is 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.

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 retry

The 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 request

The request failed validation. The message field names the first failed rule; see Common 400 messages.

401Check the key

The x-api-key header is missing, or the API key is invalid. Do not retry unchanged.

403Check the key, method and path

Access was denied, or the method and path do not exist, for example GET /v2/kyb/. Do not retry unchanged.

404Check the task ID

GET /v2/kyb/{task_id} only. The task ID is not valid, is unknown, or belongs to another organization. Do not retry. Check that you passed background_task.id from a POST request sent by your organization.

429Retry after the wait

Too many requests. Retry after the Retry-After wait or with backoff. See Rate limits.

500Fix the request, or retry

An unexpected error. A top_n that 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 backoff

A data service that Enigma depends on failed or could not be reached.

503Retry with backoff

GET /v2/kyb/{task_id} only. Enigma cannot look up background tasks right now. Your background task can still exist.

504Retry with backoff

No 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.

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 names
Provide up to two address objects
Provide up to one website
Provide 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 float
Query 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 > 1
SSN Verification is not supported for top_n > 1
TIN is missing or malformed, with tin_verification Must provide a TIN for Tin Verification
Provide a 9-digit string for EIN/TIN screening
The '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 Verification
Must provide an SSN for SSN Verification
The SSN for SSN Verification must be provided on the person object
Provide a 9-digit string for SSN screening

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:

  1. If Retry-After is present, wait at least that many seconds before you retry.
  2. Otherwise, back off as described in Retries and backoff.
  3. If you still get 429 after several retries, slow your request rate before you continue.

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.

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.

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}.