Navigate to...

Error Codes

Standard VDP Error Codes

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

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:


{
  "error": "Error Name",
  "errorDetails": "Detailed error description"
}

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