Visa Click to Pay

Merchants and Payment Service Providers

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

Error Codes and Troubleshooting

Overview

The Click to Pay API uses standardized HTTP status codes and structured error responses to communicate issues during API processing.

Error Response Structure

All Click to Pay API error responses follow a consistent structure:

{
  "status": "HTTP_STATUS_CODE",
  "reason": "ERROR_CATEGORY",
  "message": "Human-readable error description",
  "errorDetail": [
    {
      "reason": "SPECIFIC_ERROR_CODE",
      "source": "field_name_or_context",
      "sourceType": "FIELD|HEADER|PARAMETER",
      "message": "Detailed error explanation"
    }
  ]
}

Response Fields:

  • status: HTTP status code (400, 401, 403, 404, 500, etc.)
  • reason: High-level error category
  • message: General error description for developers
  • errorDetail: Array of specific error details

Common Error Scenarios

The most frequently encountered error scenarios in Click to Pay API integrations:

Authentication Failures Invalid or expired tokens, missing API keys, or incorrect credentials
Validation Errors Invalid request data, missing required fields, or format violations
Business Logic Errors Consumer not found, card enrollment failures, or transaction confirmation issues
System Errors Temporary service unavailability, timeout issues, or internal processing failures

Debugging and Troubleshooting

When encountering errors, follow this systematic approach:

  1. Examine HTTP Status Code: Determine the error category
  2. Review Error Details: Check specific error reasons and sources
  3. Validate Request Data: Ensure all required fields and formats are correct
  4. Check Authentication: Verify token and API key validity
  5. Review API Documentation: Confirm endpoint requirements and constraints
  6. Test in Sandbox: Reproduce issues in the sandbox environment
  7. Monitor Patterns: Look for recurring error patterns or trends

HTTP Status Codes

Success Status Codes (2xx)

Successful request processing with various completion states:

Code Status Meaning Click to Pay API Usage
200 OK Request processed successfully Standard success response for most API operations
202 Accepted Request accepted for processing but not yet complete Card enrollment pending validation, identity validation in progress

Client Error Status Codes (4xx)

Errors caused by client request issues:

Code Status Common Causes Resolution Actions
400 Bad Request Invalid request format, missing required fields, validation failures Review request structure, validate all required fields, check data formats
401 Unauthorized Invalid token, expired token, missing authentication Refresh token, verify API key, check authentication headers
403 Forbidden Valid credentials but insufficient permissions Verify client permissions, check SRC role configuration, contact support
404 Not Found Consumer not found, invalid endpoint, resource doesn't exist Verify consumer's identity, check endpoint URL, handle as business logic
405 Method Not Allowed Incorrect HTTP method for endpoint Use correct HTTP method (GET, POST) as specified in API documentation
409 Conflict Consumer already exists, duplicate enrollment attempt Check existing consumer status, use appropriate flow for existing consumers
422 Unprocessable Entity Valid format but business logic validation failed Review business rules, check data relationships, validate card information
429 Too Many Requests Rate limit exceeded Implement exponential backoff, respect Retry-After header, reduce request rate

Server Error Status Codes (5xx)

Errors caused by server-side processing issues:

Code Status Common Causes Resolution Actions
500 Internal Server Error Unexpected server processing error Retry with exponential backoff, contact support if persistent
502 Bad Gateway Upstream service failure, network connectivity issues Retry request, check service status, implement circuit breaker pattern
503 Service Unavailable Temporary service overload, maintenance mode Retry with exponential backoff, check service status page
504 Gateway Timeout Request timeout, slow upstream processing Retry with longer timeout, implement async processing if possible

Status Code Handling by Endpoint

Different endpoints may return specific status codes based on their functionality:

Endpoint Success Codes Common Error Codes
POST /identities/lookup 200 400 (invalid identity), 401 (auth failure), 404 (consumer not found)
POST /cards 200, 202 400 (invalid card data), 409 (consumer exists), 422 (enrollment failed)
POST /transaction/credentials 200 400 (invalid request), 404 (card not found), 422 (transaction failed)
GET /transaction/credentials 200 400 (missing parameters), 404 (card not found), 401 (auth failure)
POST /profiles/prepare 200 400 (invalid identity), 404 (profile not found), 403 (access denied)
POST /confirmations 200 400 (invalid confirmation data), 404 (transaction not found)
POST /identities/validation/initiate 200 400 (invalid request), 404 (consumer not found), 422 (validation unavailable)
POST /identities/validation/complete 200, 202 400 (invalid validation data), 422 (validation failed), 404 (session not found)

Error Response Patterns

Understanding common error response patterns helps with debugging:

Authentication Errors (401):

  • Always check both token and API key
  • Token expiration is the most common cause
  • Implement automatic token refresh

Validation Errors (400):

  • Review errorDetail array for specific field issues
  • Check required field presence and format
  • Validate data types and constraints

Business Logic Errors (404, 409, 422):

  • Handle as expected business scenarios
  • Implement appropriate user flows
  • Do not retry these errors

Server Errors (5xx):

  • Implement retry logic with exponential backoff
  • Monitor error rates and patterns
  • Set up alerting for persistent issues

Retry Logic Implementation

Recommended retry strategies for different status codes:

Immediate Retry (No Delay):

  • None - always implement some delay to avoid overwhelming the service

Exponential Backoff Retry:

  • 500, 502, 503, 504 - Server errors
  • 429 - Rate limiting (respect Retry-After header)

Limited Retry:

  • 401 - Authentication (refresh token once, then fail)

No Retry:

  • 400, 403, 404, 405, 409, 422 - Client errors

Monitoring and Alerting

Set up monitoring for different status code patterns:

Critical Alerts:

  • High rate of 5xx errors (>5% of requests)
  • Authentication failures spike (401 errors)
  • Complete service unavailability (503 errors)

Warning Alerts:

  • Increased 4xx error rates
  • Rate limiting occurrences (429 errors)
  • Business logic error patterns

Informational Monitoring:

  • Success rate trends
  • Response time by status code
  • Error distribution patterns

Troubleshooting Checklist

Systematic approach to diagnosing status code issues:

For 4xx Errors:

  1. Validate request format and required fields
  2. Check authentication credentials and headers
  3. Verify API endpoint and HTTP method
  4. Review business logic and data relationships
  5. Test with known good data in sandbox

For 5xx Errors:

  1. Check Click to Pay API service status
  2. Verify network connectivity
  3. Review request timing and size
  4. Implement retry logic if not present
  5. Contact support for persistent issues