Skip to content
API reference Get API keys

Integration · Chapter 9

Errors

Every error has the same JSON shape and a stable machine-readable code. Build your error handling on the HTTP status and code, never on the message text.

4 min read

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_id already 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 RED decision is waiting for confirmation by a second reviewer.
  • A certificate is requested for a verification that is not final (GREEN or RED).
  • A request with the same Idempotency-Key is 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_limited after Retry-After, and 500, 503 and network errors with exponential backoff (for example 1, 2, 4, 8 seconds with some jitter, up to a few attempts).
  • Do not retry other 4xx errors unchanged — fix the request or the state first.
  • Send an Idempotency-Key with every POST, PATCH and DELETE, and reuse the same key when you retry the same operation. A replayed response has Idempotent-Replayed: true. 5xx responses 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).