IDV Errors & Edge Cases

Phone Verification Failures

Error	Cause	Resolution
`VERIFICATION_SESSION_EXPIRED` (19001)	Session not completed within the 10-minute window	Create a new verification session. Consider adding a timer or progress indicator to your UX.
`VERIFICATION_SESSION_FAILED_INCORRECT_SMS_CODE` (19002)	User entered the wrong SMS code	Create a new verification session. Confirm the user is entering the code from the most recent SMS.
`VERIFICATION_SESSION_FAILED_SNA` (19003)	User not on a mobile device, or on an unsupported carrier/network	Fall back to SMS verification. SNA access attempts are limited to 5 per session.
`ENTITY_PHONE_VERIFICATION_MAX_ATTEMPTS`	Too many verification attempts for this Entity’s phone number	The underlying SMS provider has rate-limited this phone number. Wait before retrying, and surface appropriate messaging to the user.

Identity Verification Failures

Error	Cause	Resolution
`MISSING_IDENTITY_MATCH`	Method couldn’t correlate the Entity’s PII to a known identity — insufficient or incorrect PII	Update the Entity with additional fields (DOB, SSN, address) and retry. See Maximizing Success.
`VERIFICATION_SESSION_FAILED_INVALID_ANSWER` (19004)	User answered one or more KBA questions incorrectly, or a question was missing from the request	Create a new verification session — a fresh set of questions will be generated. Confirm the user is answering carefully.
`VERIFICATION_SESSION_EXPIRED` (19001)	Session not completed within the 10-minute window	Create a new verification session.

Request Errors

Error	Cause	Resolution
`MISSING_PHONE_VERIFICATION`	Attempted to create an identity verification session before phone verification was completed	Complete phone verification first, then create the identity verification session.
`EXISTING_VERIFIED_SESSION`	The Entity has already completed verification for that type (phone or identity)	No action needed — the Entity is already verified for that step.
`INVALID_ENTITY_TYPE`	Attempted to create a verification session on a corporation Entity	Verification sessions are only available for Entities of type `individual`.
`UNAUTHORIZED_VERIFICATION_METHOD`	The team is not authorized to use the requested verification method	Contact your Method CSM to enable the method (e.g., `byo_sms`, `byo_kyc`).

Edge Cases

User needs a different phone number mid-flow

An Entity’s phone number cannot be changed once it has been set. If the user entered the wrong phone number, you’ll need to create a new Entity with the correct phone number and start the verification process from the beginning.

Same phone number across multiple Entities

Multiple Entities can share the same phone number, but each Entity must complete its own verification independently.

Re-verification after Entity was previously verified

Attempting to create a verification session for an already-verified type will return EXISTING_VERIFIED_SESSION. Verification is persistent and does not need to be repeated.

Attempting verification on a disabled Entity

Verification sessions cannot be created for Entities that have been disabled. Ensure the Entity is in an active state before initiating verification.

Corporation Entity

Verification sessions are only available for individual Entities. Attempting to create a session on a corporation Entity will return INVALID_ENTITY_TYPE.

Error Code Reference

For the full list of error codes with response bodies, see the Entity Verification Session Errors reference.

Getting Started

Entities

Identity Verification

Connect

Accounts

Updates

Payments

Additional Products

Use Cases: Commerce

Use Cases: Lending

Use Cases: PFM

IDV Errors & Edge Cases