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., failed validation or authentication). Codes in the 5xx range indicate an unhandled error (these are rare and should never happen).

HTTP status code summary
The request was successfully processed and everything worked as expected.
The request was successfully processed and a new resource was created.
Bad Request
The request was unacceptable, often due to sending an unsupported parameter.
The access token was not present in the request, was expired or didn't have enough permissions.
Not Found
The requested resource was not found, often due to a wrong resource's id.
Method Not Allowed
The request method is known by the server but has been disabled and cannot be used.
Not Acceptable
The Accept header was not correctly set to application/vnd.api+json
Unsupported Media Type
The Content-type header was not correctly set to application/vnd.api+json
Unprocessable Entity
The request body was well-formed but contains semantical errors, often due to validation constraints.
The resource could not be deleted due to integrity constraints.
Too Many Requests
The request was not accepted because you hit the rate limit.
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 extra information. We recommend writing code that gracefully handles all possible API exceptions.

Example request:
PATCH /api/line_items HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

  "data": {
    "type": "line_items",
    "id": 1234,
    "attributes": {
      "quantity": 100
Example response:
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json

  "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"
      "meta": {
        "error": "less_than_or_equal_to",
        "count": 10,
        "value": 100

Get our machine-readable JSON schema that follows the OpenAPI Specification (formerly Swagger).

Get our Postman collection in one click and start making real calls to Commerce Layer API in minutes.

Get in touch with our support team if you have any questions or want to learn more about Commerce Layer.