Navigate to...

Error Codes

All errors from the Visa Platforms Login API return a standardized ErrorResponse object with an error identifier and detailed troubleshooting information. The reference includes HTTP status codes, common causes, and resolution steps to help quickly diagnose and resolve issues.

Error Response Format

All API errors return a standardized ErrorResponse object with the following structure:

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

The error field contains a brief error identifier, while errorDetails provides specific information for troubleshooting.

HTTP Status Codes

Code	Error Type	Common Causes	Resolution Steps
400	Bad Request	Invalid request format, missing required fields, schema validation failure, OFAC screening rejection, duplicate user registration	Validate request schema against API specification, check required fields, review OFAC status, verify user uniqueness
401	Unauthorized	Invalid credentials, expired authentication token, missing Authorization header, bad username/password combination	Refresh OAuth2 token, verify credentials, check authentication flow, ensure proper Authorization header format
403	Forbidden	Insufficient OAuth2 scopes, unauthorized site access, permission restrictions, client not authorized for operation	Verify OAuth2 scopes match required permissions, confirm site access rights, contact administrator for permission review
404	Not Found	User does not exist, expired activation token, invalid user ID format, resource not available	Verify user existence using search endpoints, regenerate activation tokens, check user ID format and validity
500	Internal Server Error	System unavailability, database connectivity issues, downstream service failures, unexpected processing errors	Implement retry logic with exponential backoff, check system status, contact support if errors persist

Authentication-Specific Errors

Scenario	Error Response	Resolution
Invalid login credentials	401 - Bad credentials	Verify username and password accuracy, check account status, ensure user account is activated
MFA code required but not provided	400 - Request is not valid	Include otp and otpType parameters in login request for MFA-enabled users
Expired session token	401 - Unauthorized	Refresh authentication token or re-authenticate user, implement session extension logic
Account locked or suspended	401 - Bad credentials	Check user account status, contact administrator for account unlock, review security policies

Registration and Enrollment Errors

Scenario	Error Response	Resolution
Duplicate user registration	400 - Request is not valid	Check if user already exists using search endpoints, use update operations instead of registration
OFAC screening failure	400 - Request is not valid	User requires manual review, contact compliance team, do not retry automatically
Invalid site configuration	400 - Request is not valid	Verify siteId matches environment, check site configuration, ensure proper domain mapping
Missing required locale	400 - Request is not valid	Include locale in userSiteAttributes, verify locale format matches expected values
Activation token expired	404 - Activation token expired	Generate new activation token using resend activation email endpoints

Multi-Factor Authentication Errors

Scenario	Error Response	Resolution
MFA already enrolled	400 - Request is not valid	Check MFA enrollment status before setup, use unenroll endpoint to reset if needed
Invalid TOTP code	400 - Request is not valid	Verify time synchronization on user device, ensure correct TOTP key configuration
MFA not setup for user	404 - User MFA TOTP not setup	Complete MFA setup process before attempting enrollment or unenrollment

Batch Operation Errors

Scenario	Error Response	Resolution
No users in ID range	400 - No user in given id range	Verify user ID range parameters, check user existence before batch operations
Invalid call type	400 - callType not allowed	Use supported call types: OFAC, MOE, ENROLL_PROGRAM_AND_MOE
Migration batch not found	400 - Request is not valid	Verify migration batch ID exists, check migration status using status endpoints

Diagnostic Tools and Endpoints

Connection Testing: Use /connection/test-all to validate system connectivity and identify infrastructure issues affecting API operations.
User Search and Validation: Leverage /user/queries to verify user existence and account states before performing operations that might fail due to user-related issues.
Migration Status Tracking: Monitor batch operations using /migrate/status and /migrate/batches endpoints to identify and resolve processing issues.
Error Detail Analysis: Examine the errorDetails field in error responses for specific troubleshooting information and guidance.

Retry Logic Guidelines

Retryable Errors (5xx): Implement exponential backoff for server errors. Start with 1-second delay, doubling with each retry up to maximum of 60 seconds.
Non-Retryable Errors (4xx): Do not retry client errors without correcting the underlying issue. Fix request format, authentication, or permissions before retrying.
Authentication Failures: Implement lockout protection to prevent account compromise. Limit retry attempts and implement progressive delays.
OFAC Validation Failures: Never retry OFAC rejections automatically. These require manual compliance review and cannot be resolved programmatically.

Troubleshooting Checklist

Verify API endpoint URL matches your target environment (QA, Sandbox, Production)
Confirm OAuth2 token is valid and includes required scopes for the operation
Check request payload against OpenAPI schema specification
Validate all required fields are present and properly formatted
Ensure siteId parameter matches your configured Visa platform domain
Review user account status and activation state for user-specific operations
Check system connectivity using diagnostic endpoints
Examine error response details for specific guidance
Implement appropriate retry logic based on error type
Contact Visa support for persistent issues with detailed error information