---
title: Error handling
slug: merchant-api/error-handling
createdAt: 2021-10-06T14:18:11.000Z
---

The API will return different types of error or warning according to various constraints (resources limits and authorizations, incorrect request content, missing key).

## Body structure errors in POST/PATCH methods:

Below is an example of **invalid request body** and the response returned by the API.

:::CodeblockTabs
example of invalid PATCH stocks request

```javascript
{
    "items": [
        {
            "warehouses": [],
            "quantity": "randomValue",
            "sku": "1234"
        }]
}
```
:::

The above body will trigger the below **error message** in the body of the response:

:::CodeblockTabs
corresponding error returned

```javascript
{
    "status": "error",
    "errors": [
        {
            "location": "body",
            "name": "items",
            "description": {
                "0": {
                    "quantity": [
                        "Not a valid integer."
                    ]
                }
            }
        }
    ]
}
```
:::

***

## Errors in multi-item updates

Some endpoints allow you to submit multiple items in a single request body. In case of a partially successful integration of such content, the API will return a `HTTP 207` status, returning as a response body the list of items processed.

In such instance, you should parse the response body to verify the item of each individual item:

:::CodeblockTabs
invalid item update response example

```javascript
      {
        "sku": "68471-NPO-GFM_123456",
        "quantity": 10,
        "status": {
          "message": "Sku 68471-NPO-GFM_123456 does not exist",
          "code": 404,
          "title": "Not Found"
        }
```
:::

In the above example, the item `sku` was not recognized so the update could not go through. The API will return the SKU with  a `status` object. This object always contains 3 properties:

- `title`: name of the status, generally corresponding to the HTTP status code name.
- `code`: the error code, based on standard HTTP status code to be easily understandable
- `message`: the human readable message for this status.

:::hint{type="success"}
When an endpoint returns a `status` object as the response, or includes `status` within the list of items returned, you should check the `status.code` field. If it is an error code (> 300), then you should look into `status.message` for more information.
:::

***

# Common errors

:::hint{type="info"}
These errors are common to every endpoint of the Merchant API. Please ensure you built proper logic on your end to avoid encountering these errors, or to identify and fix any issue which could cause them.
:::

## HTTP 404 -> Not found

**Response HTTP Header code :** `404`

**Cause:** The endpoint you called (or its path parameters) are not recognized. Do not resubmit a request which returned a 404 as it will be rejected once more.

**Actionable:** Fix the request before resubmitting.

**Example response:**

:::CodeblockTabs
NOT FOUND

```json
{
  "title": "Not Found",
  "code": 404,
  "message": "The Resource could not be found: {request.path}"
}
```
:::

:::hint{type="success"}
Please note that you should never receive a 404 when running your production code, as this is generally a result of erroneous implementation or lack of testing during the integration phase.
:::

## HTTP 401 -> Unauthorized\`

**Response HTTP Header code :** 401

**Cause:** You tried calling the API without submitting a valid token.

**Actionable:** Please ensure your JWT is valid before resubmitting (you can generate a token with the `POST /auth` endpoint).

## HTTP 403 -> Forbidden

**Response HTTP Header code :** `403`

**Cause:** Your token is valid but access to a specific resource was denied. You should NOT resubmit a request to the same endpoint until Neteven confirmed specific permission was granted.

**Actionable:** Get in touch with your Neteven contact to ask for the relevant permission.

**Example response:**


:::CodeblockTabs
FORBIDDEN

```json
{
	"message": "Access was denied to this resource: {request.path}",
	"code": 403,
	"title": "Forbidden",
}
```
:::

## HTTP 503 -> Service Unavailable

**Response HTTP Header code :** `503`

**Cause:** There might be a service maintenance running, hindering its availability.

**Actionable:** Please wait around 5 minutes before resubmitting your requests.