# 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