Handling errors

The complete list of response codes

Commerce Layer uses HTTP response codes to show the success or failure of an API request.

  • Codes in the 2xx range indicate success.

  • Codes in the 4xx range indicate an error that failed given the information provided (e.g. bad request, failed validation, or authentication).

  • Codes in the 5xx range indicate an unhandled error (these are rare and should never happen).

The error object

All the 4xx responses include an error object in the response body. The object contains the list of errors with some extra information.

Correct error handling is important. We recommend writing code that gracefully handles all possible API exceptions.

Examples

401 Unauthorized

The following request tries to retrieve (with sales channel API credentials) an SKU that's not sellable in the market the app has in scope (i.e. an SKU that doesn't have a price in one of the market's price list and at least one stock item in one of the market's stock location):

curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/skus/BjwqSyPrKn' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'

422 Unprocessable Entity

The following request tries to update the quantity of a line item with an out-of-range value:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/line_items/saDFGhjkLZ' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "line_items",
      "id": "saDFGhjkLZ",
      "attributes": {
        "quantity": 100
      }
    }
  }'

400 Bad Request

The following request tries to update a price but the ID in the URL does not match the one in the body:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/prices/yzkWXfgHQS' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
      "type": "prices",
      "id": "YZkWXgfQHS",
      "attributes": {
        "amount_cents": 4900
      }
    }
  }'

404 Not Found

The following request tries to fetch a non-existing SKU:

curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/skus/XxYyZzKkJj' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'

Last updated