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:
Code
Text
Description
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 only — see example).
406
Not acceptable
The Accept header was not correctly set to application/vnd.api.v1+json (learn more about versioning — see 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": "..."
     }
  }
}
Key
Type
Description
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:
Key
Type
Description
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:
Environment
Limit type
Max number of requests
Time window
Live
Average
150 (to all endpoints)
1 min
Test
Average
75 (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 20 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
Request
Response
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 API responds with a 400 Bad request status code but returns only one error (the one about the filter key):
{
  "error": {
    "title": "filter is not valid",
    "code": "BAD_REQUEST",
    "status": 400,
    "meta": {
      "errors": [
        {
          "filter": "filter can't be blank if defined"
        }
      ],
      "trace_id": "1ab23c34-de56-7fab-89cd-e0f1234a1b2c"
    }
  }
}
Request
Response
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"
      }
    }
  }'
The API responds with a 400 Bad request status code and return the details about the two syntax errors:
{
  "error": {
    "title": "request is not valid",
    "code": "BAD_REQUEST",
    "status": 400,
    "meta": {
      "errors": [
        {
          "date_breaxdown": "not valid"
        },
        {
          "filtr": "not valid"
        }
      ],
      "trace_id": "1ab23c34-de56-7fab-89cd-e0f1234a1b2c"
    }
  }
}
401 Unauthorized
Request
Response
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"
      }
    }
  }'
The API responds with a 401 Unauthorized status code due to failed authorization:
{
  "error": {
    "title": "the access token you provided is not valid or expired",
    "code": "UNAUTHORIZED",
    "status": 401
  }
}
405 Method not allowed
Request
Response
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"
      }
    }
  }'
The API responds with a 405 Method not allowed status code and returns the related request ID:
{
  "error": {
    "title": "the request method cannot be used, use POST instead",
    "code": "METHOD_NOT_ALLOWED",
    "status": 405,
    "meta": {
      "trace_id": "1ab23c34-de56-7fab-89cd-e0f1234a1b2c"
    }
  }
}
406 Not acceptable
Request
Response
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 API responds with a 406 Not acceptable status code, suggesting the list of availble versions:
{
  "error": {
    "title": "the API version in the Accept header is not supported, use v1 instead",
    "code": "NOT_ACCEPTABLE",
    "status": 406,
    "meta": {
      "trace_id": "1ab23c34-de56-7fab-89cd-e0f1234a1b2c"
    }
  }
}
Request
Response
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"
      }
    }
  }'
The API responds with a 406 Not acceptable status code, suggesting the correct header format:
{
  "error": {
    "title": "the Accept header was not correctly set to application/vnd.api.v{{version}}+json",
    "code": "NOT_ACCEPTABLE",
    "status": 406,
    "meta": {
      "trace_id": "1ab23c34-de56-7fab-89cd-e0f1234a1b2c"
    }
  }
}
415 Unsupported media type
Request
Response
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" ]
        }
      }
    }
  }'
The API responds with a 415 Unsupported media type status code, suggesting the correct header format:
{
  "error": {
    "title": "the Content-type header was not correctly set to application/vnd.api+json",
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "status": 415,
    "meta": {
      "trace_id": "1ab23c34-de56-7fab-89cd-e0f1234a1b2c"
    }
  }
}
422 Unprocessable entity
Request
Response
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 API responds with a 422 Unprocessable entity status code and returns specific information about the wrong key:
{
  "error": {
    "title": "filter is not valid",
    "code": "UNPROCESSABLE_ENTITY",
    "status": 422,
    "meta": {
      "errors": [
        {
          "order": [
          {
            "date_to": [
              "if you provide date_from you need to provide also date_to"
            ]
          }
          ]
        }
      ],
      "trace_id": "1ab23c34-de56-7fab-89cd-e0f1234a1b2c"
    }
  }
}
Request
Response
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 API responds with a 422 Unprocessable entity status code and returns specific information about the wrong key:
{
  "error": {
    "title": "query is not valid",
    "code": "UNPROCESSABLE_ENTITY",
    "status": 422,
    "meta": {
      "errors": [
        {
          "date_breakdown": [
            {
              "operator": "total it's not a valid value, must be: avg, max, min, sum, stats"
            }
          ]
        }
      ],
      "trace_id": "1ab23c34-de56-7fab-89cd-e0f1234a1b2c"
    }
  }
}
Request
Response
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"
          }
        }
      }
    }
  }'
The API responds with a 422 Unprocessable entity status code and returns specific information about the wrong keys:
{
  "error": {
    "title": "filter is not valid",
    "code": "UNPROCESSABLE_ENTITY",
    "status": 422,
    "meta": {
      "errors": [
        {
          "line_items": [
            {
              "tax_rate": [
                {
                  "in": "is not a valid operator, please use one from eq, ne, gt, gte, lt, lte, gt_lt, gte_lte, gte_lt, gt_lte"
                }
              ]
            },
            {
              "options": {
                "name": [
                  "not valid"
                ]
              }
            }
        ],
        "order": [
            {
              "gift_card_code": [
                "not valid"
              ]
            }
          ]
        }
      ],
      "trace_id": "1ab23c34-de56-7fab-89cd-e0f1234a1b2c"
    }
  }
}

Code	Text	Description
`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 only — see example).
`406`	`Not acceptable`	The Accept header was not correctly set to `application/vnd.api.v1+json` (learn more about versioning — see 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.

Key	Type	Description
`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.

Key	Type	Description
`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`.

Environment	Limit type	Max number of requests	Time window
Live	Average	150 (to all endpoints)	1 min
Test	Average	75 (to all endpoints)	1 min
Live	Burst	50 (per endpoint)	10 secs
Test	Burst	25 (per endpoint)	10 secs

FBT

Next - Getting started

Use cases

Last modified 4mo ago