# Error codes
> Every error code the API can return, collected from the API source code.
Source: https://docs.okyc.stream/reference/errors
See [errors](https://docs.okyc.stream/backend/errors.md) 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 support@okyc.stream 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 |