Handling errors
The complete list of response codes
- 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 | |
401 | Unauthorized | The access token was not present in the request, was expired, or didn't have enough permissions. |
404 | Not found | |
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 | |
500 | Internal server error | Something went wrong on our end and is being investigated by our engineers. |
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.
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):
curl -g -X GET \
'https://yourdomain.commercelayer.io/api/skus/BjwqSyPrKn' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token'
The API responds with a
401 Unauthorized
status code and returns a UNAHUTORIZED
error:{
"errors": [
{
"title": "Access denied",
"detail": "You are not authorized to perform this action on the requested resource.",
"code": "UNAUTHORIZED",
"status": "401"
}
]
}
Request
Response
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
}
}
}'
The API responds with a
422 Unprocessable Entity
status code and returns a VALIDATION_ERROR
:{
"errors": [
{
"title": "must be less than or equal to 10",
"detail": "quantity - must be less than or equal to 10",
"code": "VALIDATION_ERROR",
"source": {
"pointer": "/data/attributes/quantity"
},
"status": "422",
"meta": {
"error": "less_than_or_equal_to",
"value": 100,
"count": 10
}
}
]
}
Request
Response
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
}
}
}'
The API responds with a
400 Bad Request
status code and returns a KEY_NOT_INCLUDED_IN_URL
error:{
"errors": [
{
"title": "Key is not included in URL",
"detail": "The URL does not support the key 10272",
"code": "KEY_NOT_INCLUDED_IN_URL",
"status": "400"
}
]
}
Request
Response
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'
The API responds with a
404 Not Found
status code and returns a RECORD_NOT_FOUND
error:{
"errors": [
{
"title": "Record not found",
"detail": "The requested resource was not found. Please double-check the resource id.",
"code": "RECORD_NOT_FOUND",
"status": "404"
}
]
}
Last modified 2mo ago