Errors

The complete list of response codes you can get, how the errors object is structured, and all the information about rate limits

Commerce Layer Metrics API uses HTTP response codes to show the success or failure of each 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. due to a bad request, a failed validation, or an expired authentication).

  • Codes in the 5xx range indicate an unhandled error (these are rare and should never happen).

This is the complete list of response codes you can receive when making requests to the Metrics API endpoints:

CodeDescription

200

OK

The request was successfully processed and everything worked as expected.

400

Bad request

The request was unacceptable, often due to malformed syntax or sending an unsupported parameter at the first level (see examples).

401

Unauthorized

The access token was not present in the request, was expired, or didn't have enough permissions (see example).

404

Not found

The requested resource was not found, often due to a typo on the query type or resurce name in the endpoint.

405

Method not allowed

The request method is known by the server but has been disabled and cannot be used (Metric API supports POST request onlysee example).

406

Not acceptable

The Accept header was not correctly set to application/vnd.api.v1+json (learn more about versioningsee examples).

415

Unsupported media type

The Content-type header was not correctly set to application/vnd.api+json (see example).

422

Unprocessable entity

The request body was well-formed but contains semantical errors on a nested level, often due to validation constraints (see examples).

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.

Correct error handling is important. We recommend writing code that gracefully handles all possible API exceptions.

The error object

All the 4xx and 5xx responses include an error object in the response body. The object contains the list of errors with some extra information.

{
   "error": {
     "title": "...",
     "code": "...",
     "status": ...,
     "meta": {
       "errors": [
         {
           "field_name": [
             {
               "attribute_name": [ "..." ]
             },
             { ... }
           ]
           ...
         }
       ],
       "trace_id": "..."
     }
  }
}
KeyTypeDescription

title

String

Descriptive information about the type of error.

code

String

The HTTP response code (e.g. BAD_REQUEST, UNAUTHORIZED).

status

Integer

The HTTP response status (e.g. 400, 401).

meta

Object

Any additional information about the errors in the request. Returned for 400, 404, 422, and 500 errors only.

Errors meta

For some types of error the meta object is also returned inside the error object. It contains extra information that can help you understand what went wrong with your call to the Metrics API and why it wasn't successful:

KeyTypeDescription

errors

Array of objects

The detailed list of errors in the request (with information messages and reference to the related wrong keys). Returned for 400 and 422 errors only.

trace_id

String

The ID of the request (feel free to share it with us in case the information provided isn't enough for you to debug the error). Returned for every type of error except for 401.

Metrics API query validations are subject to a hierarchy — the filter section is validated before the query type one, hence errors in the parameters of the latter won't be thrown unless the ones in the parameters of the former are fixed (see example).

Rate limits

The requests you perform to the Metrics API are currently subject to the same rate limits as the POST requests to the Core API, based on the environment and the limit type:

EnvironmentLimit typeMax number of requestsTime window

Live

Average

200 (to all endpoints)

1 min

Test

Average

100 (to all endpoints)

1 min

Live

Burst

50 (per endpoint)

10 secs

Test

Burst

25 (per endpoint)

10 secs

The Core API /oauth/token endpoint you need to use for authentication is subject to stricter limits (max 30 reqs / 1 min).

IP addresses that exceed the rates above will be blocked until the frequency of the specific call drops below the allowed limit.

Examples

400 Bad request

The following request tries to perform a Metrics API query but both the query type and the filter keys are empty objects:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/date_breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "date_breakdown": { },
    "filter": { }
  }'

The following request tries to perform a Metrics API query with some syntax errors on the first level keys:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/date_breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "date_breaxdown": {
      "by": "order.placed_at",
      "field": "order.total_amount_with_taxes",
      "interval": "month",
      "operator": "avg"
    },
    "filtr": {
      "order": {
        "date_from": "2021-01-01T00:00:00Z",
        "date_to": "2021-12-31T23:59:00Z",
        "date_field": "current_date"
      }
    }
  }'

401 Unauthorized

The following request tries to perform a Metrics API query using a sales channel access token:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/search' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_sales_channel_access_token}}' \
  -d '{
    "search": {
      "limit": 10,
      "sort": "desc",
      "sort_by": "order.placed_at",
      "fields": [
        "order.id",
        "order.number"
      ]
    },
    "filter": {
      "order": {
        "date_from": "2021-01-01T00:00:00Z",
        "date_to": "2021-12-31T23:59:00Z",
        "date_field": "current_date"
      }
    }
  }'

405 Method not allowed

The following request tries to perform a Metrics API query using the GET method:

curl -g -X GET \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/search' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "search": {
      "limit": 100,
      "sort": "desc",
      "sort_by": "order.created_at",
      "fields": [
        "order.id"
      ]
    },
    "filter": {
      "order": {
        "date_from": "2021-01-01T00:00:00Z",
        "date_to": "2021-12-31T23:59:00Z",
        "date_field": "updated_at"
      }
    }
  }'

406 Not acceptable

The following request tries to perform a Metrics API query specifying an unsupported or not existing API version in the header:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/breakdown' \
  -H 'Accept: application/vnd.api.v3+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "breakdown": {
      "by": "order.country_code",
      "field": "order.id",
      "operator": "value_count",
      "sort": "desc",
      "limit": 20,
      "condition": {
        "gt": 1
      }
    },
    "filter": {
      "order": {
        "date_from": "2021-01-01T00:00:00Z",
        "date_to": "2021-12-31T23:59:00Z",
        "date_field": "created_at"
      }
    }
  }'

The following request tries to perform a Metrics API query using a wrong Accept header:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/breakdown' \
  -H 'Accept: application/javascript' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "breakdown": {
      "by": "order.country_code",
      "field": "order.id",
      "operator": "value_count",
      "sort": "desc",
      "limit": 20,
      "condition": {
        "gt": 1
      }
    },
    "filter": {
      "order": {
        "date_from": "2021-01-01T00:00:00Z",
        "date_to": "2021-12-31T23:59:00Z",
        "date_field": "created_at"
      }
    }
  }'

415 Unsupported media type

The following request tries to perform a Metrics API query using a wrong Content-Type header:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/stats' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: text/plain' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "stats": {
      "field": "order.id",
      "operator": "value_count"
    },
    "filter": {
      "order": {
        "date_from": "2021-01-01T00:00:00Z",
        "date_to": "2021-12-31T23:59:00Z",
        "date_field": "fulfillment_updated_at"
      },
      "shipping_address": {
        "country_codes": {
          "not_in": [ "IT", "FR", "DE" ]
        }
      }
    }
  }'

422 Unprocessable entity

The following request tries to perform a Metrics API query specifying only the date_from parameter of the filter:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/date_breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "date_breakdown": {
      "by": "order.placed_at",
      "field": "line_items.discount",
      "interval": "year",
      "operator": "stats"
    },
    "filter": {
      "order": {
        "date_from": "2021-01-01T00:00:00Z",
        "date_field": "current_date"
      },
      "line_items": {
        "discount": {
          "lt": -100
        }
      }
    }
  }'

The following request tries to perform a Metrics API query using an unsupported operator as the query parameter:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/date_breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "date_breakdown": {
      "by": "order.placed_at",
      "field": "line_items.discount",
      "interval": "year",
      "operator": "total"
    },
    "filter": {
      "order": {
        "date_from": "2021-01-01T00:00:00Z",
        "date_to": "2021-12-31T23:59:00Z",
        "date_field": "current_date"
      },
      "line_items": {
        "discount": {
          "lt": -100
        }
      }
    }
  }'

The following request tries to perform a Metrics API query using some not valid fields and operators as filter parameters:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/date_breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "date_breakdown": {
      "by": "order.placed_at",
      "field": "line_items.discount",
      "interval": "year",
      "operator": "min"
    },
    "filter": {
      "order": {
        "date_from": "2021-01-01T00:00:00Z",
        "date_to": "2021-12-31T23:59:00Z",
        "date_field": "current_date",
        "gift_card_code": {
            "in": [ "GFC00001", "GFC0001"]
        }
      },
      "line_items": {
        "discount": {
          "lt": -100
        },
        "tax_rate": {
          "in": [ 0.22, 0.1 ]
        },
        "options": {
          "name": {
            "eq": "Engraved"
          }
        }
      }
    }
  }'

Last updated