---
title: "HTTP status codes"
description: "Learn how to handle HTTP responses."
url: "https://docs.adyen.com/development-resources/response-handling"
source_url: "https://docs.adyen.com/development-resources/response-handling.md"
canonical: "https://docs.adyen.com/development-resources/response-handling"
last_modified: "2021-05-12T10:56:00+02:00"
language: "en"
---

# HTTP status codes

Learn how to handle HTTP responses.

[View source](/development-resources/response-handling.md)

After submitting an API call to Adyen, you receive a response to inform you that your request was received and processed. Depending on the HTTP status code of the response, you can build logic to handle errors.

## Requirements

| Requirement          | Description                                                                 |
| -------------------- | --------------------------------------------------------------------------- |
| **Integration type** | An [online payments](/online-payments/build-your-integration/) integration. |

## HTTP responses

| HTTP status code                                                    | HTTP status message   | Description                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [200](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) | OK                    | Request processed normally. The request message was successfully processed and produced a response. The response message varies, depending on the request method and the requested data.                                                                                        |
| [201](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201) | Created               | The request was successful and a new resource was created.                                                                                                                                                                                                                      |
| [202](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202) | Accepted              | The request was accepted, but has not been processed yet. This is not a guarantee that the request will be completed.                                                                                                                                                           |
| [204](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204) | No Content            | The server successfully fulfilled the request, and there is no additional content to send in the response.                                                                                                                                                                      |
| [301](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) | Moved Permanently     | The resource you requested moved to a different location.                                                                                                                                                                                                                       |
| [400](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400) | Bad Request           | Problem reading or understanding request. The receiving server cannot understand the request because of malformed syntax. Do not repeat the request without first modifying it. Check the request for errors, fix them, and then retry the request.                             |
| [401](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401) | Unauthorized          | Authentication required. You need to provide valid authentication credentials (username/password) to access the resource.                                                                                                                                                       |
| [403](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403) | Forbidden             | Insufficient permission to process request. You do not have the appropriate user rights to access the request. Do not repeat the request.                                                                                                                                       |
| [404](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404) | Not Found             | File not found. The server could not retrieve the resource you requested at the specified location. It is possible that the resource becomes available in the future. Usually, this happens when the URL you pass with the request is incorrect. You can make subsequent calls. |
| [405](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405) | Method Not Allowed    | The target resource does not support this method.                                                                                                                                                                                                                               |
| [406](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/406) | Not Acceptable        | The server could not produce an acceptable response.                                                                                                                                                                                                                            |
| [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) | Request Timeout       | The server did not receive a complete request message within a certain amount of time. You can retry the request.                                                                                                                                                               |
| [409](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409) | Conflict              | Resource is locked. A conflict occurred because the request was already processed or is in progress. Identify the reason for the conflict and resolve it. You can retry the request if the API returns a transient error header with value **true**.                            |
| [413](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413) | Payload too large     | The body of your request was too large. The maximum request size is 10 MB. Send the request again with a size of less than 10 MB.                                                                                                                                               |
| [422](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) | Unprocessable Entity  | Request validation error. The request is well-formed (syntactically correct), but semantically incorrect: the receiving server can read the request, but cannot understand it.                                                                                                  |
| [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) | Too Many Requests     | You have sent too many requests in a short period. To handle this issue, implement a retry mechanism that uses [exponential backoff](https://www.rfc-editor.org/rfc/rfc2988#section-5) with [jitter](https://datatracker.ietf.org/doc/html/rfc4689#section-3.2.5).              |
| [500](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) | Internal Server Error | Server could not process request. The receiving server encountered an unexpected condition that prevents it from fulfilling the request. You can also receive a 500 status code when the request is incorrect, for example because of a missing or empty mandatory field.       |
| [501](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501) | Not Implemented       | The server does not support the functionality required to complete the request.                                                                                                                                                                                                 |
| [504](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504) | Gateway Timeout       | The server, acting as a gateway or proxy, did not get a response from the upstream server in time.                                                                                                                                                                              |

## Handle 200 responses

Although an HTTP response status code of `200` means that the request was submitted correctly and Adyen processed it successfully, it does not necessarily mean that the payment or modification request was successfully executed.

When the payment response includes a `resultCode` with a value of **Refused** or **Error**, a `refusalReason` field is added. Check the [refusal reason messages](/development-resources/refusal-reasons) to learn more about the possible issues with payment or modification requests. For example:

* You send a [capture payment request](/online-payments/modify-payments).

* The response to your capture request returns an HTTP response status code of `200`. 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 will 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](/development-resources/webhooks) message that includes the information about this capture example:

  * The  `pspReference` in this notification is the same as the  `pspReference` in the capture modification response.
  * The `success` field value is **false**, and the `reason` field 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.

## Debugging APIs

While building your integration into the Adyen APIs, you can reach out to us if you need additional help.

If you contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other), 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:

| Field          | Type    | Required                                                                                    | Description                                                                                                                                              |
| -------------- | ------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`       | Integer | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Returns the [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status).                                                      |
| `errorCode`    | String  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The Adyen code that is mapped to the error message.                                                                                                      |
| `message`      | String  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A short explanation of the issue.                                                                                                                        |
| `errorType`    | String  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Returns the type of error that was encountered. The following are allowed error types:- `internal`
- `validation`
- `security`
- `configuration`         |
| `pspReference` | String  | ![-x-](/user/data/smileys/emoji/x.png "-x-")                                                | Returns the PSP reference associated with this error. If the `pspReference` is not present in the response body, check the HTTP headers of the response. |

**Example error response**

```json
{
    "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](/development-resources/error-codes).

## See also

* [HTTP status codes on MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status)
* [RFC 2616, section 6.1.1](https://tools.ietf.org/html/rfc2616)
