Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
Getting started
Getting started
  • Welcome to Commerce Layer
    • Guided setup
    • Manual configuration
  • API specification
  • API credentials
  • Authentication
    • Client credentials
    • Password
    • Authorization code
    • Refresh token
    • JWT bearer
    • Revoking a token
  • Roles and permissions
  • Fetching resources
  • Fetching relationships
  • Including associations
  • Sparse fieldsets
  • Sorting results
  • Pagination
  • Filtering data
  • Creating resources
  • Updating resources
  • Tagging resources
  • Deleting resources
  • Importing resources
  • Exporting resources
  • Cleaning up resources
  • External resources
    • External order validation
    • External prices
    • External shipping costs
    • External payment gateways
    • External promotions
    • External tax calculators
  • Rate limits
  • Handling errors
  • Real-time webhooks
  • Callbacks security
On this page
  • The error object
  • Examples

Handling errors

The complete list of response codes

PreviousRate limitsNextReal-time webhooks

Last updated 10 months ago

Commerce Layer uses 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
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.

204

No content

The request was successfully processed and an existing resource was deleted.

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

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.

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'

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"
    }
  ]
}

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
      }
    }
  }'

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
      }
    }
  ]
}

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
      }
    }
  }'

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"
    }
  ]
}

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'

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"
    }
  ]
}

The request was unacceptable, often due to sending an unsupported parameter ().

The requested resource was not found, often due to a wrong resource's ID ().

The request body was well-formed but contains semantical errors, often due to validation constraints ().

The request was not accepted because you hit one of the .

HTTP response codes
rate limits
see example
see example
see example