1. ChannelEngine Help Center
  2. REST APIs
  3. Merchant API

Articles in this section

See more

Merchant API: errors and response codes

  • Created
  • Updated

About this article

This article describes the errors and response codes you may encounter when implementing and using ChannelEngine's Merchant API.

Introduction

The Merchant API provides HTTP response codes for each request that corresponds with the body and action attempted.

Errors and response codes

Below are the most common response codes used by the Merchant API.

Code Label Description Retry
200 OK The request succeeded. The resulting meaning of ‘success’ depends on the HTTP method. No
201

CREATED

The request succeeded, and a new resource was created as a result. This is typically the response sent after POST requests, or some PUT requests.

 OK
202 ACCEPTED The request has been received, but not yet acted upon. It is noncommittal, since there is no way in HTTP to later send an asynchronous response indicating the outcome of the request. It is intended for cases where another process or server handles the request – or for batch processing. OK
400 BAD REQUEST The server cannot or is not going to process the request due to a client error. E.g.: malformed request syntax, invalid request message framing, or deceptive request routing. OK
401 UNAUTHORIZED Although the HTTP standard specifies ‘unauthorized’, semantically this response means ‘unauthenticated’. That is, the client must authenticate to get the requested response. OK
403 FORBIDDEN The client does not have access rights to the content; that is, it is unauthorized. The server refuses to provide the requested resource. Unlike 401 unauthorized, the client's identity is known to the server. OK
404 NOT FOUND

The server cannot find the requested resource. This means that the endpoint is valid, but the resource itself does not exist.

 OK
405 METHOD NOT ALLOWED

The request method is known by the server, but is not supported by the target resource. E.g.: an API may not allow calling DELETE to remove a resource.

 OK
410 GONE

This response is sent when the requested content has been permanently deleted from the server, with no forwarding address.

 OK
429 TOO MANY REQUESTS

The user has sent too many requests in a given amount of time. I.e.: rate limiting is in place.

 OK
500 INTERNAL SERVER ERROR The server has encountered a situation it does not know how to handle. OK
503 SERVICE UNAVAILABLE

The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.

 OK
401 GATEWAY TIMEOUT

This error response is given when the server is acting as a gateway and cannot get a response in time.

 Yes

Examples

Example A - 500

  1. You make a POST /v2/offer call to change the stock of an item from 5 to 0.
  2. ChannelEngine is under maintenance, so it returns an error 500 because the update cannot be processed.
  3. If this response is ignored, the stock exported to marketplaces is still 5.
  4. This can cause placed orders that need to be canceled, resulting in bad metrics on the marketplace.

Example B - 400

  1. You make a POST /v2/shipments call to create a shipment. This shipment has a single order line with a quantity of 4 products. However, you only ship 2 products – and the channel does not allow for the splitting of order lines.
  2. ChannelEngine's Merchant API returns a response 4xx because the number of shipped products submitted is lower than the expected (and accepted) number of products in the order.
  3. If this is ignored, no shipment is created and exported to marketplaces – resulting in an open order.
  4. That results in bad metrics on the marketplace, as well as customer complaints.

Example C - 200, with validation errors

  1. You make a POST /v2/offer call to update a batch of products.
  2. 50 of the 100 submitted products contain a Merchant product number for which no known products are in the ChannelEngine database.
  3. That results in the task itself succeeding, updating 50 products – and returning status code 200. However, 50 products in the update are unknown.
  4. If that is ignored, the user of the integration might erroneously expect those products to be on ChannelEngine – and available for sale on marketplaces.

Scenarios

  • If you encounter an error 500, log it and mark all affected data as not exported. If you use a scheduled solution (e.g.: cronjobs) or a real-time solution, include all data from the failed export in the next export.
  • If you encounter an error 400, log it and make it visible to the user of the integrated system. Errors 400 are most likely caused by invalid input, and tend to require some manual correction to prevent them from reoccurring. Marking them for re-export with every export is not a proper solution. The exception to this is error 429, which means you are making too many API calls to ChannelEngine in short succession. If that is the case, implement rate-limiting on your end.
  • If you encounter a code 200 for a /v2/product or /v2/offer endpoint, check and log the validation message (if any) and make it visible to the user of the integrated system. These validation errors are most likely caused by invalid input, and tend to require some manual correction to prevent them from re-occurring. Marking them for re-export with every export is not a proper solution.

Related articles

Comments

0 comments

Article is closed for comments.