> ## Documentation Index
> Fetch the complete documentation index at: https://docs.methodfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IDV Errors & Edge Cases

> Common verification errors, failure modes, and how to handle edge cases.

## 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_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](https://docs.methodfi.com/reference/entities/update-entity.md) with additional fields (DOB, SSN, address) and retry. See [Maximizing Success](https://docs.methodfi.com/guides/identity-verification/maximizing-success.md). |
| `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

> [accordion] 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.

> [accordion] Same phone number across multiple Entities
>
> Multiple Entities can share the same phone number, but each Entity must complete its own verification independently.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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](https://docs.methodfi.com/reference/errors/entity-verification-session-errors.md) reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.