Error handling

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.

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

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

{
    "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:

      {
        "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.

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

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:

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

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:

{
	"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.