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
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.
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.
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
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.
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.
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 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"
      },
      "status"=>"422",
      "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.