Dashboard

Error and Reason Code Reference

Every error VerifyHuman returns to an integration, grouped by area, with what to do about it.

Response shapes

Most endpoints use:

{"error": "Invalid API key", "status": "ERROR", "hint": "Generate a valid API key from your dashboard"}

Some add code (VerifyAge policy errors), error_type (Team API), error_code (rate limiting) or retryable. Mobile endpoints use {"success": false, "code": "...", "message": "...", "retryable": false}. Verification steps that are not finished answer 200 with "status": "ACTION_REQUIRED".

Retryable or not

HTTP Retry? Billed?
200 ACTION_REQUIRED After completing the required step No
200 UNAVAILABLE Yes, later No
400, 401, 403, 404, 409, 422 No — change the request or configuration No
402 No — add credits first No
426 No — use a flow that supports liveness No
429 Yes, after Retry-After No
5xx Yes, with exponential backoff No

Authentication and access

HTTP Error Meaning
400 Missing client key /api/verify was called without clientKey
401 Missing API key No key sent
401 Invalid API key / Invalid client key Unknown or deactivated key
401 client_secret_required / Missing client secret The endpoint needs Authorization: Bearer <client_secret>
401 Authentication required GET /api/status/{id} or the receipt endpoint without a credential
403 ScopeNotAuthorized The key's scopes exclude the product
403 Product not available on your plan Your plan excludes the product
403 Domain not allowed Browser request from a site not in the key's allowed domains
403 API key configuration error The key is misconfigured; create a new one

Billing and rate limits

HTTP Error Meaning
402 Insufficient credits. Required: N, Available: M Not enough credits; nothing charged
402 Insufficient-credits message with a verification_id The charge could not be made after the check ran; the verification is recorded as an error and not billed
402 CREDITS_EXHAUSTED No credits (rate limiter and Mobile API form)
429 RATE_LIMITED Per-key rate limit; honour Retry-After

See Credits and Billing and Rate limits.

VerifyAge policy

HTTP code Meaning
400 min_age_out_of_range Minimum age outside 18–65; body includes supported_range
400 min_age_invalid Minimum age is not a whole number
400 min_age_required An explicit minimum age is required
403 policy_reference_invalid policy_ref/hosted_token is not an active VerifyAge page of this key (other key, account, environment or product, or expired)
403 policy_reference_conflict policy_ref and hosted_token name different pages
403 policy_reference_required No server-owned policy and no client secret
409 page_policy_invalid The page's stored minimum age is invalid; it fails closed until reconfigured

POST /api/v1/verify-age/validate answers 200 with valid and a reason: valid, wrong_product, environment_mismatch, not_passed, age_evidence_missing, age_requirement_not_met, age_requirement_insufficient. An unknown or foreign verification is 404 verification_not_found. See VerifyAge.

Liveness (VerifyHuman, VerifyIdentity, VerifyTrust)

Response error Meaning
200 ACTION_REQUIRED interactive_liveness_required No liveness_session_id was supplied
200 ACTION_REQUIRED liveness_in_progress The capture has not finished
200 ACTION_REQUIRED liveness_session_expired The session expired; create a new one
200 FAIL liveness_session_invalid Unknown session, or one of another key, environment or product
200 FAIL session_consumed_elsewhere The session was already used
200 UNAVAILABLE provider_unavailable Liveness temporarily unavailable; retry later
426 LIVENESS_REQUIRED Mobile API: this product needs interactive liveness; use the Mobile App Drop-In

Hosted pages and attempts

HTTP Error Meaning
404 expired (from /hosted/status) Unknown or expired attempt token
404 not_found Attempts API: no such page, or not yours
400 invalid_product Unknown product filter
403 product_not_authorized The key or plan does not include the page's product
409 page_inactive The page is not an active persistent page
409 hosted_page_environment_mismatch Test/Live mismatch between page and key
422 product_mismatch Requested product differs from the page's product
422 invalid_return_url return_url not HTTPS, too long or not on a registered domain

See Hosted Page Lifecycle and Attempts API.

Results and receipts

HTTP Error Meaning
404 Verification not found / Not found Unknown verification, or not made with this key
404 receipt_issuance_missing A receipt was expected but not issued; contact support

Mobile API

HTTP code Meaning
4xx MISSING_REQUIRED_FIELD, INVALID_IMAGE, SESSION_WRONG_STEP, SESSION_EXPIRED Fix the request or start a new session
401 INVALID_CLIENT_KEY Unknown or deactivated key
403 SCOPE_NOT_AUTHORIZED The key's scopes exclude the product
403 POLICY_REFERENCE_INVALID VerifyAge policy_ref is not a page of this key
503 TEST_MODE_UNAVAILABLE Test keys are refused on native mobile verification endpoints
5xx SYSTEM_ERROR Temporary failure; retry

Verification reason codes

Failed or review results carry safe reason codes (in API responses as a reason field, and in receipts as reason_codes). These are the codes that may be shown to end users:

Code Outcome Visitor can retry
verification_failed fail No
selfie_no_face_detected fail Yes
selfie_multiple_faces fail Yes
face_match_failed, face_id_mismatch, selfie_id_mismatch, face_document_mismatch fail Yes
ocr_name_unreadable, ocr_dob_unreadable, ocr_address_unreadable fail Yes
id_image_unreadable fail Yes
missing_required_id_back fail Yes
id_type_not_accepted, id_type_weak, unsupported_document_type fail No
document_expired fail No
input_invalid fail Yes
compliance_data_incomplete fail Yes
id_supplemental_address_required review No
compliance_review_required review No
manual_review_required review No
unmapped_provider_response review No

Treat an unknown code as a generic failure and show your own neutral message.