Handling errors

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).
Code
Text
Description
200
OK
The request was successfully processed and everything worked as expected.
201
Created
The request was successfully processed and a new resource was created.
400
Bad request
The request was unacceptable, often due to sending an unsupported parameter (see example).
401
Unauthorized
The access token was not present in the request, was expired, or didn't have enough permissions.
404
Not found
The requested resource was not found, often due to a wrong resource's ID (see example).
405
Method not allowed
The request method is known by the server but has been disabled and cannot be used.
406
Not acceptable
The Accept header was not correctly set to application/vnd.api+json
409
Record not unique
The performed operation violates a unique constraint. You can safely ignore this warning.
415
Unsupported media type
The Content-type header was not correctly set to application/vnd.api+json
422 
Unprocessable entity
The request body was well-formed but contains semantical errors, often due to validation constraints (see example).
423
Locked
The resource could not be deleted due to integrity constraints.
429
Too many requests
The request was not accepted because you hit the rate limit (one of 600 reqs / 5 mins or 50 reqs / 10 secs).
500
Internal server error
Something went wrong on our end and is being investigated by our engineers.
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.
Rate limits
Rate limits of max 600 reqs / 5 mins and max 50 reqs / 10 secs are applied to the IP with which you perform the calls to most of the /api endpoints. The /oauth/token endpoint is subject to stricter limits (max 50 reqs / 5 mins). IPs that hit those rate limits will be blocked for the same time window (5 mins and 10 secs respectively).
Please note that it does not apply to all the resources. This is the list of the ones not subjected to any rate limit:
​Bundles​
​External promotions​
​Fixed amount promotions​
​Fixed price promotions​
​Free gift promotions​
​Free shipping promotions​
​Inventory models​
​Markets​
​Percentage discount promotions​
​Price lists​
​Prices​
​SKU lists​
​SKU list items​
​SKU options​
​SKUs​
​Stock items​
​Stock locations​
Examples
401 Unauthorized
Request
Response
The following request tries to retrieve (with a sales channel application) 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):
1
curl -g -X GET \
2
  'https://yourdomain.commercelayer.io/api/skus/BjwqSyPrKn' \
3
  -H 'Accept: application/vnd.api+json' \
4
  -H 'Authorization: Bearer your-access-token'
Copied!
The API responds with a 401 Unauthorized status code and returns a UNAHUTORIZED error:
1
{
2
  "errors": [
3
    {
4
      "title": "Access denied",
5
      "detail": "You are not authorized to perform this action on the requested resource.",
6
      "code": "UNAUTHORIZED",
7
      "status": "401"
8
    }
9
  ]
10
}
Copied!
422 Unprocessable Entity
Request
Response
The following request tries to update the quantity of a line item with an out-of-range value:
1
curl -g -X PATCH \
2
  'https://yourdomain.commercelayer.io/api/line_items/saDFGhjkLZ' \
3
  -H 'Accept: application/vnd.api+json' \
4
  -H 'Authorization: Bearer your-access-token' \
5
  -H 'Content-Type: application/vnd.api+json' \
6
  -d '{
7
  "data": {
8
    "type": "line_items",
9
    "id": "saDFGhjkLZ",
10
    "attributes": {
11
      "quantity": 100
12
    }
13
  }
14
}'
Copied!
The API responds with a 422 Unprocessable Entity status code and returns a VALIDATION_ERROR:
1
{
2
  "errors": [
3
    {
4
      "title": "must be less than or equal to 10",
5
      "detail": "quantity - must be less than or equal to 10",
6
      "code": "VALIDATION_ERROR",
7
      "source": {
8
        "pointer": "/data/attributes/quantity"
9
      },
10
      "status": "422",
11
      "meta": {
12
        "error": "less_than_or_equal_to",
13
        "value": 100,
14
        "count": 10
15
      }
16
    }
17
  ]
18
}
Copied!
400 Bad Request
Request
Response
The following request tries to update a price but the ID in the url does not match with the one in the body:
1
curl -g -X PATCH \
2
  'https://yourdomain.commercelayer.io/api/prices/yzkWXfgHQS' \
3
  -H 'Accept: application/vnd.api+json' \
4
  -H 'Authorization: Bearer your-access-token' \
5
  -H 'Content-Type: application/vnd.api+json' \
6
  -d '{
7
  "data": {
8
    "type": "prices",
9
    "id": "YZkWXgfQHS",
10
    "attributes": {
11
      "amount_cents": 4900
12
    }
13
  }
14
}'
Copied!
The API responds with a 400 Bad Request status code and returns a KEY_NOT_INCLUDED_IN_URL error:
1
{
2
  "errors": [
3
    {
4
      "title": "Key is not included in URL",
5
      "detail": "The URL does not support the key 10272",
6
      "code": "KEY_NOT_INCLUDED_IN_URL",
7
      "status": "400"
8
    }
9
  ]
10
}
Copied!
404 Not Found
Request
Response
The following request tries to fetch a non-existing SKU:
1
curl -g -X GET \
2
  'https://yourdomain.commercelayer.io/api/skus/XxYyZzKkJj' \
3
  -H 'Accept: application/vnd.api+json' \
4
  -H 'Authorization: Bearer your-access-token'
Copied!
The API responds with a 404 Not Found status code and returns a RECORD_NOT_FOUND error:
1
{
2
  "errors": [
3
    {
4
      "title": "Record not found",
5
      "detail": "The requested resource was not found. Please double-check the resource id.",
6
      "code": "RECORD_NOT_FOUND",
7
      "status": "404"
8
    }
9
  ]
10
}
Copied!
External tax calculators
Real-time webhooks
Last modified 3mo ago
Copy link
Contents
The error object
Rate limits
Examples