To determine the status of any Visa Direct API call, use the combination of the HTTP status code returned in the response, error code from Visa Direct or the platform, and other information included in the response message in order to apply the correct processing logic and communicate with customers. The following table provides additional guidance on how to interpret and act upon status responses.
| HTTP Status Code | Error Code | Error Description | Recommended Handling |
|---|---|---|---|
| 200 | None | Transaction processed successfully. The Action Code returned in the response indicates the outcome of the transaction (e.g. Approved, Declined, etc.) | Map the value in the Action Code field to an appropriate customer-facing message (e.g. "Transaction Completed Successfully" or "Transaction Declined by Recipient Issuer"). |
| 202 | None | The POST transaction timed out. If the API is not able to complete the transaction within 30 seconds (default) or within the timeout duration set in the HTTP header, it will respond with an 202 HTTP Status Code and a statusIdentifier value that can be used in the GET operation as the statusIdentifier in the URI. | Wait an appropriate amount of time and then submit a GET transaction using the statusIdentifier received in the POST response in the URL. The GET URL is valid for 24 hours and can be resubmitted as many times as needed until a successful response is returned. Consider providing a "Please Wait" type response to the customer while waiting for the transaction to complete and remind the customer not to retry the transaction because the initial request is still being processed. |
| 303 | None | The API detected a duplicate transaction. | A duplicate transaction was detected when re-submitting a POST transaction with the same header (e.g. X-Client-Transaction-ID) and details while the original transaction is still being processed. Use the GET response URL to retrieve details of the original transaction that is still in process. |
| 400 | 3001 | The transaction was rejected by Visa due to a message validation error. | The message contains invalid data. Investigate the source of the invalid data before resubmitting the transaction. Consider placing the transaction in an exception queue and providing a suitable "Try Again Later" message to the customer if the problem cannot be resolved immediately. |
| 400 | 8001 | Velocity Limit Exceeded | Established velocity limit by the service provider for transaction count, amount etc. has been reached. |
| 401 | None / 9123 / 9124 | This is returned if user credentials are wrong. | Resubmit with valid user credentials |
| 401 | 9125 | This is returned due to client certificate does not |
Use the valid client certificate |
| 403 | None / 9611 | Revalidate the URL and the Resource before resubmitting the transaction. | |
| 404 | None | The URL is invalid or the Resource could not be found. | Revalidate the URL and the Resource before resubmitting the transaction. Consider placing the transaction in an exception queue and providing a suitable "Try Again Later" message to the customer if the problem cannot be resolved immediately. |
| 404 | 3001 | The message contains an invalid Primary Account Number (PAN) | Display an appropriate message to the customer and ask them to correct the sender or recipient PAN and resubmit the request. |
| 500 | 1001 / 2001 | These are returned when an internal server error occurs. | Contact your Visa production support contact for investigation and assistance. |
| 503 | This may be due to |
Contact your Visa production support contact for investigation and assistance. Recommend not to re-post |
|
| 504 | Timeout which may be due to |
Contact your Visa production support contact for investigation and assistance. Recommend not to re-post |
Additionally, there is a specific HTTP header variable for timeout exception handling which Originators may consider to use if it is applicable to their projects. The following table lists the header details.
| HTTP Header Variable | Description |
|---|---|
| X-Transaction-Timeout-MS | This is an optional variable. Elapsed time in milliseconds (ms) in which an API will respond back. If no value is specified then it defaults to 30000 ms (i.e. 30 seconds), which is the maximum value allowed. If the set value is greater than the maximum value then timeout will not occur. The API will respond with HTTP 202 ACCEPTED if the processing has not yet completed. If the processing completes within the designated timeout period, then the API will return HTTP 200 OK and the XML- or JSON-formatted response, based on the Content-Type value. |
| HTTP STATUS CODE | ERROR MESSAGE | RECOMMENDED HANDLING |
|---|---|---|
| 400 | 597 - Consistency Err: Multiple Duplicate Requests | This request was identified as Duplicate, but the ‘SystemTraceAuditNumber Number’ is different from original request. Re-submit the transaction with the unique values for retrievalReferenceNumber, acquiringBin, cardAcceptor.terminalId or cardAcceptor.idCode to avoid the duplicate transaction and consistency errors. |
| 400 | 600 - Consistency Err: Acct Nbr Inconsistent | This request was identified as Duplicate, but the ‘Account Number’ is different from original request. Re-submit the transaction with the unique values for retrievalReferenceNumber, acquiringBin, cardAcceptor.terminalId or cardAcceptor.idCode to avoid the duplicate transaction and consistency errors. |
| 400 | 601 - Consistency Err: Trans inconsistent w/Trans history
|
This request was identified as Duplicate, but the ‘Amount’ is different from original request. Re-submit the transaction with the unique values for retrievalReferenceNumber, acquiringBin, cardAcceptor.terminalId or cardAcceptor.idCode to avoid the duplicate transaction and consistency errors. |
Start a Project
API Overview
API Reference