Error format
{
"error": {
"code": "validation_failed",
"message": "The given data was invalid.",
"fields": {
"external_id": ["The external id field is required."]
},
"request_id": "req_01m6yyj5gq0x3c7d2n8v5kp4rt"
}
}
| Field | Notes |
|---|---|
code |
Stable error code from the table below |
message |
Human-readable explanation in English. It may change; do not parse it |
fields |
Only with validation_failed: field name → list of messages. Rely on the field name, not the text |
request_id |
Same as the X-Request-Id response header. Include it when you contact support |
HTTP statuses
| Status | Meaning |
|---|---|
200 / 201 |
Success / created |
202 |
Accepted: the action continues in the background (applicant deletion, a RED review waiting for a second reviewer) |
400 |
The request is malformed or fails validation |
401 |
The API key is missing, unknown or revoked |
403 |
The key is valid, but the action is not allowed for this account |
404 |
Not found — or it belongs to another account or environment |
409 |
Conflicts with the current state |
413 |
File too large |
422 |
Well-formed, but cannot be processed |
429 |
Rate limit or plan limit reached |
500 |
Unexpected error on our side |
503 |
A dependent service is temporarily unavailable |
Error codes
| HTTP | code |
When | What to do |
|---|---|---|---|
| 400 | bad_request |
Malformed JSON, a wrong Idempotency-Key format, an invalid parameter |
Fix the request |
| 400 | validation_failed |
A field is missing or invalid; see fields |
Fix the listed fields |
| 401 | unauthenticated |
Missing, unknown or revoked API key | Check the Authorization header and the key |
| 403 | forbidden |
The account is not active | Contact support |
| 403 | tenant_not_verified |
A live key is used before business verification | Finish business verification — see Sandbox and live |
| 404 | not_found |
The ID does not exist, belongs to another account or environment, or the path is wrong | Check the ID and the key environment |
| 409 | conflict |
The action does not fit the current state (see below) | Read the current state and act on it |
| 409 | idempotency_conflict |
The same Idempotency-Key was used with a different request |
Use a new key for a new request |
| 413 | file_too_large |
An uploaded file is over the limit | Send a smaller file |
| 422 | unprocessable |
Unknown or deleted flow; more than 10 webhook endpoints |
Fix the value or remove an endpoint |
| 429 | rate_limited |
Too many requests | Wait Retry-After seconds and retry |
| 429 | plan_limit_reached |
The monthly live limit of your plan is used up | Wait for the next month or change the plan |
| 500 | internal_error |
Unexpected error | Retry with backoff; contact support with request_id if it persists |
| 503 | aml_unavailable |
Sanctions screening is temporarily unavailable | Retry later |
| 503 | certificate_unavailable |
The certificate cannot be generated right now | Retry later |
Common 409 conflict cases:
- An applicant with this
external_idalready exists in this environment (fields.external_id). - A session is requested for an applicant that is not in
init— reset the applicant first. - The verification is not
ON_HOLD, is outdated, or another reviewer is working on it. - A
REDdecision is waiting for confirmation by a second reviewer. - A certificate is requested for a verification that is not final (
GREENorRED). - A request with the same
Idempotency-Keyis still running.
The Direct API uses the same envelope with its own codes (for example invalid_file, image_too_large); they are listed in its chapter.
The hosted page returns 410 for an expired, used or unknown session link, and kyc.js reports link_invalid, session_expired or network in onError. Create a new session in these cases.
Rate limits
| Scope | Limit |
|---|---|
All /api/v1 requests |
600 per minute per API key |
Requests with include= (document data, identity) |
30 per minute per API key |
| Webhook test and delivery retry | 10 per minute per API key |
GET /documents/catalog (no key) |
60 per minute per IP |
| Direct API | 120 per minute per IP and 60 per minute per key environment |
Responses include X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get 429 rate_limited with a Retry-After header in seconds.
429 plan_limit_reached is different: it is your monthly live quota, not a per-minute limit, and retrying does not help until the quota frees up. Check it with GET /usage.
Retries and idempotency
- Retry
429 rate_limitedafterRetry-After, and500,503and network errors with exponential backoff (for example 1, 2, 4, 8 seconds with some jitter, up to a few attempts). - Do not retry other
4xxerrors unchanged — fix the request or the state first. - Send an
Idempotency-Keywith everyPOST,PATCHandDELETE, and reuse the same key when you retry the same operation. A replayed response hasIdempotent-Replayed: true.5xxresponses are not saved, so a retry after a server error runs again. See Authentication. - If a create request timed out without an
Idempotency-Key, look the object up before creating it again — for example,GET /applicants?external_id=…. - For decisions, prefer webhooks to polling. Webhook deliveries are retried for about a day — see Webhooks.
Versioning
The version is part of the path: /api/v1. Within v1 changes are additive only:
- new endpoints, optional request fields, response fields, webhook event types, reject labels, check names and error codes may be added;
- existing fields, values and codes are not renamed or removed.
Write your client to ignore unknown fields and to handle unknown values gracefully — for example, treat an unknown reject label like ON_HOLD. A breaking change would come as a new version (/api/v2).