Customer Enrollment & KYC

Errors

Common error code Values returned across Customer Enrollment & KYC endpoints.

Use this page to

Look up what a code in an error response means
Decide how to handle each error type in your integration
Understand when to prompt for a re-submission vs. when it's a duplicate

Code	HTTP	Meaning
`INVALID_REQUEST`	400	Missing/invalid field, unsupported `type`, or a per-type requirement not met
`NOT_FOUND`	404	Customer not found for your business
`CONFLICT`	409	This `type` (or facial verification) is already `approved`
`DUPLICATE_REQUEST`	400	A `pending` submission for this `type` already exists
`DUPLICATE_IDENTITY`	400	This BVN is already registered to another customer profile
`DUPLICATE_ACCOUNT`	400	`customerid`, email, or phone already registered for this business
`PROVIDER_ERROR`	400	Verification provider (e.g. Veriff) could not be reached
`REQUEST_FAILED`	400	The request could not be completed
`UNAUTHORIZED`	401	Business not found or inactive

Error shape

{
  "status": "error",
  "code": "DUPLICATE_REQUEST",
  "message": "A pending submission for this type already exists."
}

Handling recommendations

Situation	Recommended handling
`INVALID_REQUEST`	Check the required-fields table for the `type` you're submitting
`NOT_FOUND`	Confirm the `uuid` you're using is correct
`CONFLICT`	This item is already approved, no action needed, don't resubmit
`DUPLICATE_REQUEST`	A submission is already under review check. Retrieve KYC State instead of resubmitting
`DUPLICATE_IDENTITY`	This BVN belongs to another customer profile. Investigate before proceeding
`DUPLICATE_ACCOUNT`	This `customerid`, email or phone is already enrolled; look up the existing customer instead of re-enrolling
`PROVIDER_ERROR` / `REQUEST_FAILED`	Transient, retry after a short delay
`UNAUTHORIZED`	Check your access token and business status
`IDENTITY_LOCKED`	Attempted to change `firstname`, `lastname`, `dob`, or `nationality` after KYC approval, account provisioning, or card issuance; see Update Customer
`CUSTOMER_HAS_CARDS`	Attempted to delete a customer with a card that isn't terminated; see Delete Customer
`CUSTOMER_HAS_ACTIVITY`	Attempted to delete a customer with an account that has already received funds; see Delete Customer

Note: Reviews are asynchronous for document types — poll Retrieve KYC State, or subscribe to the KYC Status Update webhook for real-time notice instead of polling continuously.

Questions? Email [email protected]. Also on GitBook.