Error codes
The following business logic error codes are specific to Visa Platforms Login:
Product-Specific Error Codes
Business Logic Errors
Error responses use application/problem+json content type for detailed error information, while some endpoints may use standard application/json.
Data Validation 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 |
System-Specific 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 |
OFAC and VBA Integration 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 |
| 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:
{
"error": "Error Name",
"errorDetails": "Detailed error description"
}
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.