Visa Intelligent Commerce
Errors and troubleshooting
Available for use by:
Merchants
Independent developers
Error codes are named strings from the API response schema, not raw HTTP status codes. Use the named code field from the OpenAPI spec.
Standard Visa Developer error codes
Product-specific error codes
Business logic errors
| Error Code | HTTP Status | Description | Cause | Resolution |
|---|---|---|---|---|
| DECLINED | 200 (in TransactionResponseWithPendingEvents.status) | Purchase instruction has been declined | Example: purchase mandates breached | Validate transaction parameters against the mandate before resubmitting; do not retry unchanged |
| EXPIRED | 200 (in TransactionResponseWithPendingEvents.status) | Purchase instruction has expired | Mandate or token validity window elapsed | Create a new instruction; do not retry the expired one |
Data validation errors
| Error Code | HTTP Status | Description | Validation Rule | Resolution |
|---|---|---|---|---|
| CURRENCY_MISMATCH | 200 (within BusinessError.details) | Currency of the transaction does not match an expected value | Transaction currency must match the mandate/token currency | Correct the currency code and resubmit |
| THRESHOLD_EXCEEDED | 200 (within BusinessError.details) | Transaction amount exceeds the mandate's declineThreshold | Amount must be within the mandate's decline threshold | Reduce the amount or use a different mandate |
| AUTHORIZATION_EXPIRED | 200 (within BusinessError.details) | The authorization window has elapsed | Authorization tokens are time-bound | Re-authenticate and retry with a fresh authorization |
| PROCESSING_ERROR | 200 (within BusinessError.details) | An internal processing error occurred for this detail | Not applicable | Retry with exponential backoff; escalate if persistent |
System-specific errors
| Error Code | HTTP Status | Description | System Behavior | Common Mistake | Resolution |
|---|---|---|---|---|---|
| INTERNAL | 500 | Internal server error | Report to Visa | Rarely a client-side mistake | Retry with backoff; escalate if persistent |
| INVALID_ARGUMENT | 400 | Malformed or invalid request | errorDetail[].reason: INVALID_FIELD identifies the offending field | A field exceeds its documented length or array-size limit, or encryptedInstruction is malformed | Correct the request and resubmit |
| PERMISSION_DENIED | 403 | client identity or origin not validated | errorDetail[].reason: FORBIDDEN_RESOURCE | Calling an endpoint or environment your client isn't yet approved for | Verify client credentials and resource access |
| NOT_FOUND | 404 | Referenced resource not found | errorDetail[].reason: RESOURCE_NOT_FOUND | Reusing a tokenId or instructionId across environments (sandbox, certification, production are separate) | Verify the consumer identity, clientExternalId, or instructionId |
| UNAUTHENTICATED | 401 | Authorization token validation failure | errorDetail[].reason: INVALID_CREDENTIALS | An expired mutual TLS certificate, or an agentSignature with a stale expires timestamp or reused nonce | Verify mutual TLS, agent signature, and credentials |
| CONFLICT | 409 | Requested action cannot be performed | Cancel attempted before a required prior step (such as confirmation) was completed | Calling Cancel before "Confirm transaction events" when a credential has already been retrieved | Complete the required prior step (such as confirmation) and retry |
| RATE_LIMIT_EXCEEDED | 429 | Rate limit exceeded | Retry-After header indicates wait time | Not yet documented; rate-limit thresholds and enforcement scope are unconfirmed | Wait per Retry-After before retrying |
Response field enum values
BusinessError.category: high-level classification of a declined/expired transaction
| Value | Meaning | Developer action |
|---|---|---|
| VALIDATION_ERROR | The request failed a validation rule | Correct the offending field and resubmit |
| AUTHORIZATION_ERROR | An authorization-related failure occurred | Re-authenticate; do not retry unchanged |
| PROCESSING_ERROR | An internal processing failure occurred | Retry with backoff; escalate if persistent |
| LIMIT_ERROR | A threshold or limit was exceeded | Adjust the amount or mandate; do not resubmit unchanged |
Error response format
{
"status": "400",
"reason": "INVALID_ARGUMENT",
"message": "Invalid DPA ID",
"errorDetail": [
{ "reason": "INVALID_FIELD", "message": "Invalid clientExternalId" }
]
}
Copied!
Common integration issues
Issue: Retrying without correcting the underlying failure
- Typical Error: UNAUTHENTICATED / CONFLICT
- Cause: Retrying an authentication failure without collecting fresh authentication data, or retrying against an expired instruction/token
- Solution: Refresh the authentication data or create a new instruction before retrying; never resubmit a 400-level error unchanged
Issue: Transaction parameters not validated against the mandate before submission
- Typical Error: DECLINED (THRESHOLD_EXCEEDED)
- Cause: Amount or merchant not validated against the mandate's declineThreshold before the call
- Solution: Validate transaction parameters against the consumer's mandate client-side before submitting
Error handling best practices
- Distinguish retryable from non-retryable failures: Use exponential backoff for temporary unavailability; never retry authentication failures or expired resources without first refreshing the underlying credential.
- Validate before you call: Check transaction parameters against the mandate's declineThreshold and effectiveUntilTime before submitting a credential-retrieval request.
Environment-specific errors
- Sandbox: No documented deviation from production error behavior.
- Certification: Not documented in this spec.
- Production: No documented deviation beyond standard error codes.
Known limitations
- Real-time transaction visibility/status is not currently available to Agent Providers.
- Merchants that attempt to create a card-on-file token from an agentic token will currently fail.
For support: developer.visa.com/pages/support
See also: PCI SSC recurring / CVV guidance.