Error codes

All error responses use the same envelope:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "request_id": "req_01j..."
  }
}

code is stable — treat it as the machine-readable identifier. message is human-readable and may change between releases. request_id is always echoed in the KYC-Request-Id response header.

Catalog

Code	HTTP	Meaning
`authentication_required`	401	No credentials were supplied.
`invalid_api_key`	401	API key is malformed, revoked, or belongs to another mode.
`session_expired`	401	Portal/admin session or SDK token has expired.
`permission_denied`	403	The caller is authenticated but lacks the required role.
`tenant_suspended`	403	The tenant account is suspended.
`live_mode_not_activated`	403	Live keys refused because billing is not set up.
`insufficient_balance`	402	Prepaid wallet cannot cover the next verification.
`plan_not_found`	404	Requested plan slug is not active in `billing_plans`.
`topup_not_found`	404	AIO callback referenced a top-up the platform doesn't know.
`invalid_signature`	401	AIO or Stripe webhook signature failed verification.
`not_found`	404	The resource does not exist or is not visible to this caller.
`verification_not_found`	404	Verification ID unknown within this tenant.
`method_not_allowed`	405	HTTP method mismatch.
`idempotency_conflict`	409	Same `Idempotency-Key` reused with a different body.
`verification_not_cancelable`	409	Verification has already reached a terminal state.
`check_not_required`	422	The iframe tried to submit a check that the resolved flow does not require.
`validation_error`	422	Request body failed schema validation. Details in `fields`.
`rate_limited`	429	Rate limit exceeded. Retry after `Retry-After` seconds.
`internal_error`	500	Something broke on our side. Request ID required when filing.
`dependency_unavailable`	503	A downstream service (AI, database, queue) is currently down.

Always log the request ID

When something goes wrong, record the request_id — it's the fastest way for us to trace the request through the platform.

Error codes

Catalog

Always log the request ID

On this page