Visa Pay

Start a Project Start a Project API Overview API Overview API Reference API Reference
Navigate to...
keyboard_arrow_down

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