Error reference

Error reference

Every error response shares the same envelope:

{
  "error": {
    "type": "https://docs.checktiv.com/api/errors/<code>",
    "code": "<code>",
    "message": "<human readable>",
    "request_id": "req_…",
    "doc_url": "https://docs.checktiv.com/api/errors/<code>",
    "param": "<optional, names the offending field>",
    "details": { … }
  }
}

The doc_url points back here. Click any code below for triage guidance and a sample body.

HTTP 401

Code	Retryable	Summary
authentication_required	No	No API key was supplied with the request.
invalid_api_key	No	The API key is malformed, unknown, expired, or revoked.

HTTP 402

Code	Retryable	Summary
payment_required	No	The wallet cannot cover the operation: insufficient balance, or a locked/closed wallet.

HTTP 403

Code	Retryable	Summary
subscription_required	No	The wallet balance is frozen after a subscription cancellation.
insufficient_scope	No	The key is valid but lacks the scope required for this endpoint.
mode_mismatch	No	A live key was used to access a test resource (or vice versa).
access_denied	No	The request was refused by a platform security control.

HTTP 404

Code	Retryable	Summary
resource_not_found	No	The requested resource does not exist within your organisation.

HTTP 409

Code	Retryable	Summary
region_mismatch	No	The key was issued in a different region than the endpoint.
session_already_completed	No	The session is in a terminal state and cannot be modified.
idempotency_conflict	No	The same `Idempotency-Key` was reused with a different request body.
version_conflict	Yes	Optimistic concurrency check failed.
default_template	No	You tried to delete the workflow template set as your default.
active_group_links	No	One or more active verification links still reference the workflow template you tried to delete.
active_connector_connections	No	One or more connector connections use this workflow template as their default and are blocking the delete.
link_slug_taken	No	The chosen link slug is already in use by another verification link in your account.
group_link_no_reinvite	No	The session was started from a shared link, so it cannot be re-invited or issued a fresh invite link.

HTTP 410

Code	Retryable	Summary
org_shredded	No	The organization has been crypto-shredded under Article 17 (right to erasure); its data is no longer accessible.

HTTP 413

Code	Retryable	Summary
payload_too_large	No	The request body exceeded the per-endpoint size limit.

HTTP 415

Code	Retryable	Summary
unsupported_media_type	No	The request `Content-Type` is not accepted for this endpoint.

HTTP 422

Code	Retryable	Summary
validation_error	No	The request body or query parameters failed schema validation.
document_unreadable	No	The uploaded document image could not be read by the ID scan API.

HTTP 429

Code	Retryable	Summary
rate_limit_exceeded	Yes	The caller exceeded its rate limit.

HTTP 500

Code	Retryable	Summary
internal_error	Yes	An unhandled error occurred inside the API.
pdf_render_failed	Yes	The session report PDF could not be generated.

HTTP 502

Code	Retryable	Summary
provider_error	Yes	An upstream provider (KYC vendor, bureau, etc) failed.

HTTP 503

Code	Retryable	Summary
billing_unavailable	Yes	The billing-state cache could not be read; the request was refused to avoid silently bypassing quota.
service_unavailable	Yes	The ID scan service is temporarily unavailable.
pdf_binding_missing	Yes	The PDF report service is temporarily unavailable.