Visa Direct Error Codes

Error Codes and Exception Handling

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 matched with the one issued by Visa.  Use the valid client certificate
403 None / 9611 The URL access is not permitted. 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 network connectivity issue. Contact your Visa production support contact for investigation and assistance. Recommend not to re-post transaction and check settlement report.
504   Timeout which may be due to network connectivity issue. Contact your Visa production support contact for investigation and assistance. Recommend not to re-post transaction and check settlement report.

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.

Timeout Exception Handling

Timeout exception handling diagram

Repost transaction with different Retrieval Reference Number (RRN)

  • Original transaction has been processed by Visa
Original transaction diagram
  • Original transaction is being processed by Visa
Original transaction diagram 2

GET Request with Different Responses

  • Retry GET request if response is timeout
Original transaction diagram 3
  • Incorrect URL or GET request has already been sent
Original transaction diagram 4
  • Transaction status is not known
Original transaction diagram 5