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
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
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
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
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
Corporation Entity
Verification sessions are only available for individual Entities. Attempting to create a session on a corporation Entity will return
INVALID_ENTITY_TYPE.