VICA reports failures in three different places depending on the operation. Read the table that matches where you saw the error - the same reason code can mean different things in different contexts (see the callout below).
| Where the error appears | Operations | What to read |
|---|---|---|
| Synchronous HTTP response (immediate) | Request-level validation and business-rule rejections on any call | HTTP Status Codes, VIDC Reason Codes (synchronous) |
| Asynchronous outcome (Request Status / Notification) | Enroll, Manage, Delete (returned 202, then completed) | Click to Pay Reason Codes |
| Get Data item result (in the data[] array, HTTP 200) | Get Data, per product | Get Data Item-Level Error Codes |
| Status | Meaning | When |
|---|---|---|
| 200 OK | Request processed synchronously | Get Data, Request Status. Note: a 200 does not mean every product succeeded - inspect each item. |
| 202 Accepted | Request accepted for asynchronous processing | Enroll, Manage, Delete. Outcome arrives via Request Status or Notification. |
| 400 Bad Request | Validation or business-rule failure | Missing/invalid fields (VIDC-1xxx), business-rule rejections (VIDC-2xxx) |
| 409 Conflict | Concurrency conflict | A prior request for the same consumer is still in flight (VIDC-3000) |
| 422 Unprocessable Entity | Operation not supported for the target product | AVS consumer-level operations (Manage Consumer, Delete Consumer) |
| 500 Internal Server Error | Server-side failure | VIDC-5000 |
Returned on the immediate HTTP response of a call (typically 400, 409, or 500).
| HTTP | Reason code | Meaning |
|---|---|---|
| 400 | VIDC-1000 | Required field missing |
| 400 | VIDC-1001 | Invalid value / Request ID not found |
| 400 | VIDC-1002 | Length checks failed |
| 400 | VIDC-1003 | Array length failed |
| 400 | VIDC-2000 | Consumer is already enrolled - Enroll Data |
| 400 | VIDC-2001 | Consumer is not enrolled - Enroll Payment Instruments, Manage Consumer Information, Manage Payment Instruments Data, Get Data, Delete Consumer Information, and Delete Payment Instruments Data) |
| 400 | VIDC-2002 | Entitlement checks failed - Enroll Data, Enroll Payment Instruments |
| 409 | VIDC-3000 |
Concurrent checks failed - Enroll Payment Instruments, Manage Consumer Information, Manage Payment Instruments Data, Get Data, Delete Consumer Information, and Delete Payment Instruments Data For example, when an Issuer sends Enroll Data request for consumer_1 and then sends Enroll Payment Instruments for the same consumer_1. If the Enroll Data request is not yet completed, then the Enroll Payment Instruments request will get a concurrency error response. |
| 409 | VIDC-3001 | Duplicate request detected. This error will occur when there is an in-progress Enroll Data or Enroll Payment Instrument request for the same consumer and payment instrument. |
| 500 | VIDC-5000 | Internal service error |
VIDC-3000 example: an issuer sends Enroll Data for consumer_1, then sends Enroll Payment Instruments for the same consumer_1 before the first request completes. The second request receives a concurrency error.
| Code | Returned when |
|---|---|
| VIDC-1000 | A required field is missing from the request (e.g., externalConsumerID, countryCode). |
| VIDC-1001 | A field value is invalid (wrong format, unsupported enum value, value out of allowed range), or the referenced resource (consumer or payment instrument) does not exist in ADS. |
| VIDC-1002 | A string field exceeds its maximum allowed length (e.g., externalConsumerID > 100 chars, lastName > 35 chars). |
| VIDC-1003 | An array field contains more entries than the allowed maximum (e.g., more than 5 phones or emails). |
| VIDC-2000 | An Enroll Consumer request is submitted for a consumer who is already enrolled in ADS. |
| VIDC-2001 | A Manage Consumer, Delete Consumer, or payment instrument operation references a consumer who is not enrolled in ADS. |
| VIDC-2003 | A payment instrument is submitted with an expirationDate that has already passed. |
| VIDC-2004 | An Enroll Payment Instrument request is submitted for an instrument (matched by type + accountNumber) that is already enrolled in ADS for this consumer. |
| VIDC-2005 | A Manage or Delete Payment Instrument request references an instrument that is not enrolled in ADS for this consumer. |
| VIDC-2008 | An update request attempts to change a field that cannot be modified after enrollment — specifically, phones[0] (the alias identifier stored in Alias Directory). |
| VIDC-5000 | An internal ADS service error occurred. Retry the request; if the error persists, investigate ADS service health. |
Returned in the asynchronous outcome for Click to Pay — in the details[] of the Request Status response or a Status Notification.
| Reason code | Meaning |
|---|---|
| VIDC-1000 | Required field missingTBC |
| VIDC-1001 | Invalid value / Request ID not found |
| VIDC-1002 | Length checks failed |
| VIDC-1003 | Array length failed |
| VIDC-2000 | Consumer is already enrolled – Enroll Data |
| VIDC-2001 | Consumer is not enrolled - Enroll Payment Instruments, Manage Consumer Information, Manage Payment Instruments Data, Get Data, Delete Consumer Information, and Delete Payment Instruments Data |
| VIDC-2002 |
Payment instrument is not issued by the Issuer that sends the request - Enroll Data, Enroll Payment Instruments, Manage Payment Instruments Data, and Delete Payment Instruments Data For example: Issuer A sends a request with card_1, and card_1 is issued by Issuer B. |
| VIDC-2003 | Payment instrument is expired |
| VIDC-2004 | Payment instrument already exist |
| VIDC-2005 | Payment instrument is not enrolled |
| VIDC-2006 | Payment instrument is not a Visa card |
| VIDC-2007 | Payment instrument's issuer is not configured for Issuer Offered Click to Pay |
| VIDC-2008 |
This information cannot be updated. This currently applies to expirationDate. |
| VIDC-2009 | The consumerInformation.externalConsumerID already exist. Please use Manage Consumer to update email/mobile |
| VIDC-2010 |
The provided externalConsumerId has reached the maximum number of cards allowed. Note: The number of payment instruments that may be associated with an externalConsumerId is 10. |
| VIDC-7000 | Payment instrument's tokenization declined / PAN is not eligible for tokenization |
| VIDC-5000 | Internal Service Error |
Returned per product inside the data[] array of a Get Data response. The overall HTTP status is always 200; a failed product reports an errorDetails object (product-keyed items) or an error string (intent-keyed CTP items).
| Reason Code | Meaning | Products that may return it |
|---|---|---|
| VIDC-1005 | The requested operation is not supported for the specified product in VICA. | ANI, AVS |
| VIDC-2001 | Consumer is not enrolled in the requested product. | CTP, ADS |
| VIDC-3001 | Duplicate request detected. This error will occur when there is an in-progress Enroll Data or Enroll Payment Instrument request for the same consumer and payment instrument. | CTP, AVS |
| VIDC-4000 | Request timed out while retrieving data for this product | CTP, ADS |
| VIDC-4001 | Downstream service is temporarily unavailable. Please retry at a a later time. | CTP, ADS |
When a request targets multiple products, each product is processed independently. A failure in one product does not fail the others or reject the request at the HTTP level.
Per-item error structure. Product-keyed failures use a structured errorDetails object; intent-keyed CTP failures use a top-level error string (legacy format).
Start a Project
API Overview
API Reference
"errorDetails": {
"reason": "VIDC-1002",
"message": "Request timed out while retrieving data for this product",
"details": [
{
"location": "consumerInformation.externalConsumerID",
"reason": "Lookup exceeded the processing window"
}
]
}
The errorDetails object contains:
| Field | Description |
|---|---|
| reason | A VIDC- reason code |
| message | Human-readable description of the failure |
| details | Array of objects, each with a location (field or path where the error occurred) and a reason (explanation at that location) |
Terminal vs. in-progress states. Notifications are sent only after all processing is complete, so every details[] item is terminal (SUCCESS/FAILED). The Request Status API, by contrast, may return IN_PROGRESS for a product-keyed item that is still processing. Inspect the details[] array to determine which products completed and which need follow-up.
| Symptom | Likely cause | Recommended action |
|---|---|---|
| 409 / VIDC-3000 | A prior request for the same consumer is still processing | Wait for the first request to reach a terminal state (poll Request Status), then retry |
| Get Data item VIDC-1002 (timeout) | Transient retrieval timeout for one product | Retry that product separately; other products' results are valid |
| Get Data item VIDC-1001 | Consumer not enrolled in that product | Expected when the consumer was never enrolled in that product - not a transient error |
| Get Data item VIDC-1003 | Product does not support Get Data (AVS/ANI) | Do not retry - Get Data is unsupported for that product by design |
| VIDC-2002 on a payment instrument | The card is not issued by the requesting issuer | Verify the PAN belongs to your BID before submitting |
| VIDC-2010 | Consumer already has the maximum 10 cards | Delete an existing card before enrolling a new one |
| Request Status returns nothing | requestTraceId expired | The requestTraceId is valid for 7 days; capture outcomes within that window or rely on the Status Notification |
| VIDC-7000 | PAN not eligible for tokenization | The card cannot be enrolled into Click to Pay; surface to the cardholder accordingly |