Visa Offers Network

The Visa Offers Network (VON) API returns structured error responses that include detailed information to help diagnose and resolve issues. All error responses follow a consistent JSON format with standard HTTP status codes.

Error responses typically include:

• HTTP status code indicating the general category of error
• Error code providing specific error identification
• Error message with human-readable description
• Field-specific details when applicable
• Reason codes for additional context

When request validation fails, the API returns detailed field-level error information including the specific field name, error code, and description of the validation issue.

The Visa Offers Network (VON) API uses standard HTTP status codes to indicate the success or failure of API requests:

The response handling guidelines are as follows:

• 2xx Success Codes – Process the response data normally. The request was successful and the response contains the expected information.
• 4xx Client Error Codes – Review the request for errors. These codes indicate issues with the request format, authentication, or permissions that need to be corrected.
• 5xx Server Error Codes – Implement retry logic with appropriate delays. These codes indicate temporary server issues that may resolve with retry attempts.

Bulk operations like offer creation may return partial success with detailed error reporting for failed items.

• errorResults – Array of failed items with specific error details
• responseCode – Response status code for the bulk operation
• resultCounts – Summary of total, success, and error counts
• successResults – Array of successfully processed items
• responseMessage – Response message describing the operation result

Robust error handling ensures stable Visa Offers Network (VON) API integrations by gracefully managing issues and providing meaningful feedback to both users and developers.

1. Implement HTTP status code checking for all API responses. Always check the status code before processing response data. Handle success (2xx), client error (4xx), and server error (5xx) codes appropriately.
2. Parse error response bodies to extract detailed error information. VON API error responses include structured JSON with error codes, messages, and field-specific details that help identify the root cause.
3. Implement retry logic for transient server errors (5xx status codes). Use exponential backoff for retries: wait 1 second, then 2 seconds, then 4 seconds, etc. Limit the number of retry attempts to avoid infinite loops.
4. Handle client errors (4xx) by validating request format and required fields. Check for missing or invalid parameters that cause 400 Bad Request responses. Verify endpoint URLs and resource identifiers to avoid 404 Not Found errors.
5. Implement field-level validation error handling for form inputs. Use the details array in error responses to highlight specific fields that need correction and provide targeted guidance.
6. Log error details for debugging and monitoring purposes. Include request IDs, timestamps, error codes, and relevant context information in your logs for troubleshooting.
7. Handle bulk operation errors by processing both success and error results. For operations like offer creation, some items may succeed while others fail. Process successful items and report specific errors for failed items.
8. Implement circuit breaker patterns for repeated failures. If an endpoint consistently fails, temporarily stop making requests to prevent cascading failures and allow time for recovery.

Error codes for Payload and URI, AuthN, AuthZ, Internal Server, and Rate or Quota can be found on Visa Developer Error Codes.

These tables provide a comprehensive reference of error codes returned by the Visa Offers Network (VON) APIs, including technical error codes, descriptions, user-facing messages, and operational impact.

These are the standard ErrorResponse schema structures used across Visa Offers Network (VON) API endpoints.

• ErrorResponse Properties
  • reason – Reason for the error (maxLength: 100, minLength: 1, example: "Bad Request")
  • status – HTTP Status Code (format: int32, minimum: 0, maximum: 599, example: 200)
  • message – Error Message (maxLength: 1000, minLength: 1, example: "Invalid Request")
  • errorCode – Error Code (maxLength: 500, minLength: 1, example: 400)
  • details – Array of ErrorDetail objects (List of Error Details)
• ErrorDetail Properties
  • field – Field Name (maxLength: 200, minLength: 1, example: "field")
  • reason – Reason (maxLength: 200, minLength: 1, example: "reason")
  • errorCode – Error Code (maxLength: 200, minLength: 1, example: "errorCode")
  • errorDesc – Error Description (maxLength: 200, minLength: 1, example: "errorDesc")
• IdentifierErrorDetail Properties
  • reason – Error reason (string)
  • message – Error message (string)
  • errorCode – Error code (string)
  • merchantIdentifierIndex – Index of the merchant identifier (format: int32)
• ErrorResult Properties (used in BulkMerchantResponse)
  • index – Index position (format: int32)
  • reason – Error reason (string)
  • message – Error message (string)
  • errorCode – Error code (string)
  • merchantId – Merchant ID (string)
• ErrorResult-1 Properties (used in BulkOfferResponse variants)
  • index – Index position (format: int32)
  • reason – Error reason (string)
  • message – Error message (string)
  • offerId – Offer ID (string)
  • errorCode – Error code (string)
  • merchantId – Merchant ID (string)
• Special Response Schemas with Error Handling
  • MerchantResponse – Contains errorDetails array of ErrorResponse objects
  • OfferAllResponse – Contains errorDetails array of ErrorResponse objects, sftpErrors array of strings
  • Consumer Enrollment opt-out endpoints – Use generic object schema with additionalProperties of string type