Visa Developer Error Codes

BAD REQUEST

This error could be due to a variety of reasons.

Check for the following:

• The url has a space after the ?.
• Whitespace issues, in general, anywhere in the url.
• Ideally the following fields need to be checked for correctness:
  •  URL
  •  Query params

Or

• The API endpoint you are trying to use only supports Two-Way SSL authentication. Please ensure you are not using any other token type.

Or

• Invalid input found in the request payload.

NOT FOUND

The project is trying to hit an endpoint that does not exist.

Refer to the API documentation to validate you are hitting the right endpoint.

METHOD NOT ALLOWED

The project is trying to hit an URI/http method combination that does not exist. 

Refer to the API documentation to validate you are hitting the right endpoint.

UNSUPPORTED MEDIA TYPE

The project is using an unsupported content type in the request.

Depending on the authentication/encryption mechanism being used, this could be due any of the following reasons. If you are unable to root-cause the same from the possible reasons below, please contact Visa Support at [email protected] with the details of the error message, and full http request, response details.

Two-Way SSL (Mutual Authentication):

• Authorization Header missing in the request.
• Authorization Header in invalid format. It either does not start with 'Basic' or the userId or password fields are blank.
• UserId or Password or Subject DN on the certificate is invalid.
• You could be presenting a wrong client certificate for that environment.
   

X-Pay Token:

• x-pay-token is blank or not in valid format.
• Timestamp field not in valid UTC timestamp format.
• Version field is invalid.
• Token's timestamp is more than 8 minutes off from the current time.
• Token hash mismatch.
• APIKey not present in request.
• APIKey is not active.
• APIKey not valid.
• APIKey not active.
• The request contains an older version of x-pay-token than supported by the API/project. Please upgrade to the latest supported version. Consult the VDP Getting Started Guide for the same.
   

JWE: 

• JWE Token format is invalid.
• Kid not present in the token.
• Token validation against Shared secret failed.
• JWT Grant Type or Token value is either missing, empty or has multiple values.
   

JWS:

• JWS token validation failed.
• Kid extraction from header failed.
• JWT Grant Type or Token value is either missing, empty or has multiple values.
• Kid missing in JWS header.

JWS/JWE:

• JWT prefix not in proper format.
• JWT in Request Body not a well-formed JSON.
• JWT does not contain grant type field or grant type field is blank.
• JWT does not contain assertions field or assertions field is blank.
• JWT token value does not start with the appropriate bearer_JWT prefix.
• APIKey is not active.
• APIKey not valid.
• APIKey not active.
   

This could be due to any of the following scenarios in Message Level Encryption (JWE):

• KeyId in request is invalid.
• KeyId not present in the request (JWE Header/Request Header).
• JWE payload element in request is not in the proper format.
• JWE token does not have iat header or token has expired.
   

General:

• Request has more than one authentication tokens which is not supported.
• Incoming http request does not contain any of the required authentication tokens for this API.

FORBIDDEN

403

The 403 (Forbidden) HTTP Status code indicates that this project does not have permission to access the requested resource. This can happen if you are trying to invoke API request for a resource that is not part of your project e.g. if you have created a project with Visa Direct Product but are trying to use the same credentials to access Visa Consumer Transaction Controls.

Check for the following:

• You are using a project and the credential for the project which includes the API being accessed.
• Create a project and receive sandbox credentials for the API’s being called.
• Add the API being called (if not already included) to the project with credentials that are being used.

INTERNAL SERVER ERROR

500

Internal Server Error.

Please contact Visa Support at [email protected] with a complete error message, full http request and response details.

TOO MANY REQUESTS

429

The project has clocked too many requests in a given amount of time. 

Please contact Visa Support at [email protected] if you want to increase the time limits.

503

The Visa system is currently unable to handle the request due to a temporary overloading or maintenance of the server.

Please contact Visa Support at [email protected] if the issue persists.