# Visa Platforms Login

## Error Codes

### Standard VDP Error Codes

For common HTTP status codes and standard Visa error codes, see:

[Visa Developer Error Codes](https://developer.visa.com/pages/visa-developer-error-codes)

The following business logic error codes are specific to Visa Platforms Login:

### Product-Specific Error Codes

#### Business Logic Errors

| Error Code | Description | Cause | Resolution |
| --- | --- | --- | --- |
| 400 | Request is not valid, callType not allowed, or no user in given ID range | Revalidation request with unsupported callType or invalid user ID range | Verify callType is OFAC, MOE, or ENROLL_PROGRAM_AND_MOE and ensure user IDs exist in range |
| 401 | User is locked out from passwordless login | Passwordless login lockout due to failed attempts or domain validation | Wait for lockout period to expire or use standard password authentication |
| 400 | User does not exist, alias is not valid, or alias already exists | Alias management conflicts or validation failures | Verify user exists, alias format is valid, and alias is unique within the tenant |
| 404 | User not found, or user MFA TOTP not set up | MFA enrollment attempted without proper setup sequence | Ensure MFA TOTP setup is completed before attempting enrollment |

#### Data Validation Errors

| Error Code | Description | Validation Rule | Resolution |
| --- | --- | --- | --- |
| 400 | Request is not valid or domain is invalid | Site domain restrictions by environment | Verify site domain matches the environment: QA uses rvcom-qa variants, Production uses www.visa variants |
| 400 | Request has invalid/missing inputs | Required field validation or format constraints | Ensure all required fields are present and properly formatted per schema |
| 404 | Activation token expired | Account activation attempted with expired token | Request new activation email and use fresh token |

#### System-Specific Errors

| Error Code | Description | System Behavior | Resolution |
| --- | --- | --- | --- |
| 403 | Access forbidden. Insufficient permissions to perform requested action | OAuth2 scope restrictions or role-based access denial | Verify OAuth2 token includes required scopes for the endpoint |
| 401 | Session cannot be extended, or client is not authorized | Session extension failure due to session state or client authorization | Fall back to full authentication workflow |
| 400 | Users (userDetailsId1 or userDetailsId2) not found | Duplicate account cleanup requires valid existing user IDs | Verify both user IDs exist before attempting cleanup operation |

#### OFAC and VBA Integration Errors

| Response | Description | System Behavior | Resolution |
| --- | --- | --- | --- |
| VBA: Challenge | Password flagged for additional verification | VBA system recommends additional authentication steps | Implement additional verification or require password change |
| VBA: Reject | Password compromised or unsafe | VBA system identified compromised password | Require immediate password change before allowing access |
| Guest Enrollment Failure | OFAC sanctions screening failure | User denied by OFAC screening will not be activated | Review OFAC compliance requirements and user data accuracy |

#### Error Response Format

Visa Platforms Login error responses follow this format:

```json

```

Error responses use `application/problem+json` content type for detailed error information, while some endpoints may use standard `application/json`.

### Troubleshooting and Best Practices

#### Common Integration Issues

**Issue: Pre-enrollment Preparation Problems**  
Typical Error: 400 Bad Request with validation failures  
Cause: Clients struggle most with pre-enrollment preparation requiring clean data, accurate consent handling, and correct payload construction.  
Solution: Ensure data readiness, proper consent management, and payload validation before submission. Focus on enrollment quality over enrollment speed.

**Issue: Business Process Misalignment**  
Typical Error: Various validation and business rule violations  
Cause: Misalignment between business processes and enrollment flow rather than connectivity issues.  
Solution: Align consent management, data readiness, program-specific requirements, and error handling with Visa Platforms Login business logic before technical integration.

**Issue: Authentication Delegation Assumptions**  
Typical Error: Authentication scope or permission errors  
Cause: Clients assume Visa Platforms Login behaves like a delegated identity or OAuth service rather than a secure enrollment and activation platform.  
Solution: Understand that issuers authenticate API calls while Visa owns the consumer login and credential lifecycle. No consumer-level authentication artifacts are exchanged via the API.

#### Error Handling Best Practices

When handling Visa Platforms Login errors:

- **Design for Definitive Responses:** Visa Platforms Login responses represent definitive enrollment decisions, not transient states. Handle strict validation, expected rejections, and decoupled consumer login behavior.
- **Account for Asynchronous Processing:** OFAC screening and migration operations process asynchronously. Implement appropriate polling or notification handling for eventual consistency.
- **Implement Proper Retry Logic:** Use exponential backoff for transient failures, but avoid bulk retries that may indicate systemic data or process issues.
- **Validate Scope Permissions:** Many errors result from insufficient OAuth2 scopes. Verify scope assignments match endpoint requirements before troubleshooting other causes.

#### Environment-Specific Errors

- **Sandbox:** Site domain validation errors for non-test domains; OFAC screening uses test databases
- **Certification:** Full validation testing available; email delivery behavior may differ from production
- **Production:** Live OFAC screening, full email delivery, complete scope availability

Error patterns are consistent across environments, but validation strictness and external system integration vary by environment level.

### Support

For general VDP support: [developer.visa.com/pages/support](https://developer.visa.com/pages/support)