After submitting an API call to Adyen, you receive a response back to inform you that your request was received and processed. Depending on the HTTP status code of the response, you should build some logic to handle any errors that a request or the system may return.
|HTTP status code
|HTTP status message
|Adyen status message
Request processed normally
The request message has been successfully processed, and it has produced a response.
Problem reading or understanding request
The receiving server cannot understand the request because of malformed syntax.
You need to input valid authentication credentials (username/password) to access the resource.
Insufficient permission to process request
You do not have the appropriate user rights to access the request.
Do not repeat the request.
File Not Found
It was not possible to retrieve the resource you requested at the specified location.
It may or may not become available again in the future.
Usually, this happens when the URL you pass with the request is incorrect.
You may make subsequent calls.
Payload too large
Request Entity Too Large
The body of your request was too large. The maximum request size is 10MB.
Request validation error
The request is well-formed (syntactically correct), but semantically incorrect: the receiving server can read it, but it cannot understand it.
Internal Server Error
Server could not process request
The receiving server encountered an unexpected condition that prevents it from fulfilling the request.
Our servers may return a 500 status code also when the request is incorrect, for example because of a missing or not filled in mandatory field.
Handle 200 responses
An HTTP 200/OK response status code means that the request was submitted correctly and Adyen processed it successfully. An HTTP 200 response does not automatically mean that the payment or the modification request was successfully executed.
When the payment response includes a
resultCode with a value of
refusalReason field is added. Check the refusal reason messages to learn more about the possible issues of the payment or the modification request.
- You send a capture payment request.
The response to your capture request returns HTTP 200/OK. This means:
- We received your request.
- We will execute a payment capture.
- We still do not know if the capture operation will be successful or not.
- We'll let you know in the corresponding webhook event.
- If the capture operation fails, for example, because the acquirer declines to accept the shopper's card, the payable amount for the transaction is not collected.
Based on your settings, you'll receive a webhook message that includes the information about this capture example:
pspReferencein this notification is the same as the
pspReferencein the capture modification response.
successfield value is
false, and the
reasonfield includes a short message to explain the cause of the failure.
Handle 4xx and 5xx responses
In the following scenarios, the Adyen payments platform does not accept or store submitted requests:
- The request does not pass validation.
- The request violates a security constraint.
- The request violates a configuration constraint.
- An internal error occurs on the Adyen payments platform.
In these cases, you receive an error message with an error code containing a description of the problem.
In general, you should handle it as an exception.
There is no charge for rejected payment requests accompanied by an error message.
While building your integration into the Adyen APIs, you may need to reach out to us for additional help.
If you contact our Support Team, provide the
pspReference returned in the header of the API response. The
pspReference is a unique ID for that specific API request, and can be used by our Support Team to identify specific API calls.
Error response fields
In case of an error, the response object contains the following fields:
Returns the HTTP status code.
Returns the Adyen code that is mapped to the error message.
Returns the message, a short explanation of the issue.
Returns the type of error that was encountered.
Allowed error types:
Returns the PSP reference associated with this error.
The following example shows a possible error response:
"status" : 403,
"errorCode" : "901",
"message" : "Invalid Merchant Account",
"errorType" : "security"
For the complete list of error codes and corresponding messages, see Error codes and messages.