Visa Pay
Error Codes
Reference guide for Visa Pay API error codes, causes, and resolution steps.
HTTP Status Codes
Visa Pay API uses standard HTTP status codes to indicate request success or failure:
| Status Code | Description | Meaning |
|---|---|---|
| 200 | OK | Request processed successfully |
| 201 | Created | Resource created successfully |
| 400 | Bad Request | Invalid request payload or parameters |
| 401 | Unauthorized | Authentication credentials invalid or missing |
| 404 | Not Found | Requested resource does not exist |
| 409 | Conflict | Request conflicts with current resource state |
| 500 | Internal Server Error | Unexpected server condition occurred |
Application Error Codes
Visa Pay API returns specific error codes in response payloads:
| Error Code | Description | Common Causes | Resolution Steps |
|---|---|---|---|
| INVALID_REQUEST | payload validation failure | Missing required fields, invalid data format, constraint violations | Review request payload against schema requirements, validate field formats and constraints |
| CONFLICT | Idempotency key already used | Duplicate enrollment attempt, repeated transaction with same key. Device ID has already been enrolled for device token enrollment | Check existing enrollment status, use unique idempotency keys for new requests. For additional tokens use endpoint "Add Token to Enrollment" |
| NOT_FOUND | Enrollment or token not found | Invalid external ID, deleted enrollment, expired token. The Account_ID has not been previously enrolled; GET call and 'Add Token' cannot be used before initial enrollment has taken place. | Verify external ID exists, check enrollment status, validate token lifecycle |
| INTERNAL_ERR | Unexpected system condition | Service unavailability, processing failure, network issues. Visa Pay side server error | Implement retry with exponential backoff, contact support for persistent issues |
Authentication Error Handling
Authentication failures require specific resolution approaches:
- Invalid Credentials: Verify server key and secret accuracy
- Expired Token: Regenerate access token using refresh token
- Insufficient Permissions: Confirm account has required roles and permissions
- Token Format Error: Validate JWT structure and signing algorithm
Validation Error Details
Request validation errors provide detailed field-level information:
- Required Field Missing: Include all mandatory fields in request payload
- Invalid Data Type: Ensure field values match expected data types
- Constraint Violation: Verify field values meet length, format, and range requirements
- Enum Value Error: Use only supported enumeration values
Retry Logic Guidelines
Implement appropriate retry strategies based on error type:
- Network Timeouts: Retry with exponential backoff up to 3 attempts
- 500-level Errors: Implement circuit breaker pattern with backoff
- 400-level Errors: Do not retry, fix request payload issues
- Authentication Errors: Refresh token before retry
Diagnostic Tools
Use these tools for troubleshooting and monitoring:
- Correlation IDs: Track requests end-to-end across systems
- Validation Results: Review detailed validation status arrays
- Network Metadata: Analyze ISO 8583 message processing details
- Enrollment Status: Monitor card provisioning progress
Performance Considerations
Optimize error handling for performance:
- Authorization requests must complete within 3-second timeout
- Cache authentication tokens to minimize overhead
- Monitor rate limits and implement request throttling
- Log transaction attempts for audit and troubleshooting