Error codes

See errors for the response shape and how to handle each type. The list includes codes from the hosted flow and dashboard APIs; the public API returns a subset. Messages are for developers and may change; branch on type and code.

Type	HTTP status	Codes
`invalid_request`	400	64
`authentication`	401	5
`permission`	403	15
`not_found`	404	12
`conflict`	409	17
`idempotency`	409	2
`rate_limit`	429	3
`provider_unavailable`	503	2
`internal`	500	2

invalid_request (400)

Code	Message
`address_incomplete`	Complete the address fields
`capability_not_allowed`	`{capability} is only available in KYB workflows`
`capability_unsupported`	`{capability} is not supported for {country}`
`challenge_expired`	Start the selfie step again
`challenge_required`	challenge_id is required
`challenge_used`	Start the selfie step again
`code_expired`	The code has expired. Request a new one.
`consent_first`	The consent step must be first
`consent_incomplete`	All purposes must be accepted
`consent_outdated`	The consent notice changed — reload and read it again
`consent_required`	Workflows must start with a consent step
`corrupt_image`	The image could not be read
`country_mismatch`	`Workflow {id} verifies {country}`
`country_required`	`country is required for generic check {key}`
`documents_missing`	`Missing: {missing}`
`documents_required`	`{key}: list at least one document`
`duplicate_document`	`Document {type} is listed twice`
`duplicate_step_key`	`Duplicate step key {key}`
`empty_file`	The file is empty
`face_match_reference_missing`	`face_match_against references {ref}, which is not in the workflow`
`file_required`	file is required
`file_too_large`	Files must be 10 MB or smaller
`https_required`	Webhook URLs must use https
`invalid_challenge`	Request a new code
`invalid_doc_type`	Choose a supported document
`invalid_idempotency_key`	Idempotency-Key is too long
`invalid_origin`	`Invalid origin {origin}`
`invalid_purpose`	Unknown upload purpose
`invalid_retention`	retention_days must be between 30 and 3650
`invalid_role`	`Role must be one of {allowed}` Unknown role
`invalid_value`	`{label}: {reason}`
`invalid_workflow`	Workflow definition is invalid
`malware_detected`	The file was rejected by the virus scanner
`method_required`	`Choose one of: {methods}`
`multipart_required`	Send multipart/form-data with a "file" field
`name_required`	Each person needs a name name is required
`no_changes`	Nothing to correct
`no_test_data`	This step has no test data; complete it on screen
`not_a_consent_step`	Not a consent step
`not_an_otp_step`	Not an OTP step
`persons_required`	Add at least one person
`private_url`	Webhook URLs must be publicly reachable
`reason_required`	Choose why the check is rejected
`redirect_not_allowed`	`redirect_url origin {origin} is not allowlisted`
`related_workflow_required`	related_persons steps need related_workflow_id
`selfie_required`	A selfie is required
`session_required`	`{check_key} needs a hosted session (evidence or liveness)`
`step_not_configured`	Step has no check
`steps_incomplete`	`Complete these steps first: {incomplete}`
`steps_required`	Choose the steps to redo
`too_many_persons`	At most 25 related persons
`too_many_projects`	`An organization can have up to {max_projects} projects — ask us at [email protected] for more`
`unknown_check`	`Unknown check {check} ({country})`
`unknown_document`	`Not requested: {unknown}`
`unknown_evidence`	Upload the file again
`unknown_field`	`{key} is not a field of this document`
`unknown_method`	`{capability} has no method {method} in {country}` `No method {method}`
`unknown_provider`	`Provider {unknown} is not registered (add its definition and credentials first)`
`unsupported_check`	`{key} is not available for {country}`
`unsupported_country`	`No country pack for {country}` `No country pack for {country}…`
`unsupported_file_type`	Upload a JPEG, PNG, WebP, PDF, ZIP or XML file
`use_dedicated_endpoint`	Use the consent/OTP endpoints for this step
`workflow_type_immutable`	type and country cannot change between versions
`wrong_code`	That code is not correct

authentication (401)

Code	Message
`invalid_api_key`	Invalid or revoked API key
`missing_api_key`	Provide a secret API key: Authorization: Bearer sk_…
`missing_session_token`	Provide a session token
`not_signed_in`	Sign in required
`token_expired`	Session token expired or invalid

permission (403)

Code	Message
`access_requests_closed`	OKYC is not taking access requests right now
`email_not_verified`	Verify your email address before creating live keys — check your inbox for the link
`insufficient_role`	Only an owner can change or remove an owner Only an owner can invite another owner Only an owner can make someone an owner Only owners and admins can remove members `Requires one of: {allowed}`
`invalid_signature`	Link expired or invalid
`invitation_email_mismatch`	This invitation is for a different email address
`ip_not_allowed`	This API key cannot be used from this IP address
`live_key_requires_admin`	Only admins can create live keys
`no_tenant`	Select or create a project first
`not_a_member`	You are not a member of the organization that owns this project
`not_correctable`	Only data read from uploaded documents can be corrected; government-verified results are locked
`not_manual`	Only manually verified checks can be confirmed; registry results are locked
`override_requires_admin`	Only admins can override a final decision
`sandbox_only`	Only available for test sessions
`test_mode_only`	Switch to Test mode to create sessions from the dashboard Switch to Test mode to try a draft
`two_factor_required`	Turn on two-factor authentication to continue — it is required for owners and admins

not_found (404)

Code	Message
`api_key_not_found`	api key not found
`check_not_found`	check not found
`evidence_not_found`	evidence not found
`invitation_not_found`	No pending invitation with that id This invitation does not exist
`member_not_found`	No such member on this team
`project_not_found`	project not found
`screening_hit_not_found`	screening hit not found
`session_not_found`	session not found
`step_not_found`	step not found
`webhook_endpoint_not_found`	webhook endpoint not found
`workflow_not_found`	workflow not found
`workflow_version_not_found`	workflow version not found

conflict (409)

Code	Message
`already_a_member`	This person is already on the team
`consent_required`	Consent must be given first
`decision_final`	`This session is {status}; data can only be corrected before a final decision` `This session is {status}; manual checks can only be reviewed before a final decision`
`integration_not_configured`	`This workflow cannot run live yet — {blockers}. Remove the step or configure the integration.`
`invitation_expired`	This invitation has expired — ask for a new one
`invitation_used`	This invitation has already been used or was revoked
`last_owner`	A team needs at least one owner — make someone else an owner first
`manual_checks_pending`	`Confirm or reject the manually verified checks first: {pending}`
`not_decidable`	`Session is {status}; decisions are possible in review (or as an override of a final decision)`
`not_waiting`	Only KYB sessions waiting for related persons can be advanced
`session_closed`	`Session is {status}` `This verification is {status}`
`session_expired`	This verification link has expired
`session_processing`	Checks are still running; try again in a moment
`session_submitted`	This verification was already submitted
`step_completed`	This step is already complete
`step_processing`	This step is being verified
`too_many_attempts`	No attempts left for this step

idempotency (409)

Code	Message
`idempotency_in_progress`	A request with this Idempotency-Key is in progress
`idempotency_key_reused`	This Idempotency-Key was used with a different request

rate_limit (429)

Code	Message
`otp_rate_limited`	Too many codes requested. Try again in a few minutes.
`too_many_attempts`	Too many wrong attempts. Request a new code.
`too_many_requests`	Too many requests. Try again in an hour.

provider_unavailable (503)

Code	Message
`no_provider`	`No provider is configured for {check_key}`
`scanner_unavailable`	`File scanner unavailable: {message}`

internal (500)

Code	Message
`internal_error`	An internal error occurred
`tenant_create_failed`	Could not create the organization

invalid_request (400)Copy Anchor Link

authentication (401)Copy Anchor Link

permission (403)Copy Anchor Link

not_found (404)Copy Anchor Link

conflict (409)Copy Anchor Link

idempotency (409)Copy Anchor Link

rate_limit (429)Copy Anchor Link

provider_unavailable (503)Copy Anchor Link

internal (500)Copy Anchor Link

On this page