# Error responses When the [GraphQL API](/en/documentation/devtools/graphql/) refuses a request, it returns an HTTP status code and a JSON body with one key, `detail`, that holds the message. The body never carries a GraphQL `errors` array. The errors fall into four groups: authentication, query construction, query limits, and access and rate. A request to a path that is not one of the five GraphQL endpoints returns `204` with an empty body, not an error message. --- ## Error format Every error body has the same shape. This query goes to `https://api.azion.com/v4/metrics/graphql` with the header `Authorization: Bearer [TOKEN VALUE]`, which the API does not accept: ```graphql { __typename } ``` The API returns `401` with the message in `detail`: ```json { "detail": "Authentication credentials were not provided." } ``` The tables below show each `detail` value as the message reads. A message that spans several lines in the body is shown on one line. --- ## Authentication errors Authentication errors return `401`. The API accepts one header form on every endpoint, `Authorization: Token [TOKEN VALUE]`: | Status | `detail` | Cause | Fix | | ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------- | | `401` | `Authentication credentials were not provided.` | The request has no `Authorization` header, or the header uses `Bearer` instead of `Token`. | Send the header `Authorization: Token [TOKEN VALUE]`. | | `401` | `Invalid Token` | The `Authorization` header carries a value that is not a valid token. | Send a valid personal token in the header. | | `401` | `The authorization token has expired.` | The token in the header has expired. | Send a token that has not expired. | --- ## Query construction errors Query construction errors return `400`. The API checks the query against the schema of the endpoint and the rules of each argument. When a field, dataset, or argument name is close to a valid one, the message ends with `Did you mean`, followed by the valid names: | Status | `detail` | Cause | Fix | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | `To execute queries it is mandatory to provide the desired time interval.` | A query to the metrics or events endpoint has no time window in `filter`. | Add `tsRange`, or `tsGt` and `tsLt`, to `filter`. | | `400` | `The start and end dates must have the same timezone.` | One bound of the time window has a time zone suffix, such as `Z`, and the other has none. | Write both bounds without a suffix, which the API reads as UTC, such as `2026-10-03T13:00:00`. Both bounds with the same offset, such as `-03:00`, are also accepted and converted to UTC. | | `400` | `The query includes fields that require grouping. Please ensure all non-aggregated fields are included in groupBy argument.` | The query selects a measure field, such as `requests`, directly. | Read the measure through `aggregate`, such as `aggregate: { sum: requests }`, and select the function output, `sum`. | | `400` | `Query syntax error. In resample queries, you must provide the timestamp (ts) field in the group_by parameter and you must include the group_by fields in the selected fields to return data. To query data without resampling, remove the resample parameter from the query.` | The query uses `resample` without `ts` in `groupBy`. | Add `ts` to `groupBy` and to the selected fields, or remove `resample`. | | `400` | `Cannot query field "requestz" on type "WorkloadMetricsAggregatedFieldsLogType". Did you mean "requests", "requestTime", "requestMethod", "requestLength" or "requestsTotal"?` | The query selects a field that the dataset does not have. The message names the field and the type of the dataset. | Select a field the dataset lists, such as one of the names the message suggests. | | `400` | `Cannot query field "workloadMetric" on type "Query". Did you mean "workloadMetrics" or "workloadBreakdownMetrics"?` | The dataset name does not exist on the endpoint. | Correct the dataset name. | | `400` | `Cannot query field "workloadEvents" on type "Query". Did you mean "workloadMetrics" or "workloadBreakdownMetrics"?` | The dataset belongs to another endpoint. Here, the query sends an events dataset to the metrics endpoint. | Send the query to the endpoint that serves the dataset, here `https://api.azion.com/v4/events/graphql`. | | `400` | `Unknown argument "limits" on field "workloadMetrics" of type "Query". Did you mean "limit"?` | The query passes an argument that the dataset does not accept. Here, the name is misspelled. | Correct the argument name. | | `400` | `Unknown argument "resample" on field "workloadEvents" of type "Query".` | The query uses `resample` on an events dataset. Only metrics datasets accept `resample`. | Remove `resample`, or query a metrics dataset. | | `400` | `Argument "groupBy" has invalid value [ts, invocationsss]. In element #1: Expected type "WorkloadMetricsGroupByFields", found invocationsss.` | A value in `groupBy` is not a field the dataset can group by. The message counts elements from zero. | Replace the value with a field the dataset lists for `groupBy`. | | `400` | `Argument "filter" has invalid value {tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"}, hostname: "x"}. In field "hostname": Unknown field.` | `filter` names a field that the dataset does not have. The message repeats the whole filter. | Use a filter field the dataset lists. | | `400` | `Argument "filter" has invalid value {tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"}, statusEq: "200"}. In field "statusEq": Expected type "Int", found "200".` | A filter value has the wrong type. Here, a string was passed to an integer field. | Pass the value in the type the message names, here `statusEq: 200`. | | `400` | `Syntax Error GraphQL (2:109) Expected Name, found {` | The query is not valid GraphQL. The message gives the line and column of the error, then an excerpt of the query. | Correct the query at the line and column the message names. | A time window whose `begin` is later than its `end` is not refused: the API returns `200` with an empty array. This query to `https://api.azion.com/v4/metrics/graphql` is missing the `)` that closes the arguments of `workloadMetrics`: ```graphql query { workloadMetrics(limit: 3, filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} } { ts } } ``` The API returns `400`, and `detail` carries the position, an excerpt of the query, and a caret under the column of the error: ```json { "detail": "Syntax Error GraphQL (2:109) Expected Name, found {\n\n1: query {\n2: workloadMetrics(limit: 3, filter: { tsRange: {begin: \"2026-09-26T14:00:00\", end: \"2026-10-03T14:00:00\"} } {\n ^\n3: ts\n" } ``` --- ## Query limit errors Query limit errors stop a query that asks for more rows, fields, or data than one query can read. The bounds themselves are on [GraphQL API limits](/en/documentation/devtools/graphql/limits/): | Status | `detail` | Cause | Fix | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `400` | `The value for the query limit is invalid (must be between 0 to 10000 rows).` | `limit` is outside the range from 0 to 10000, such as `10001` or `-1`. | Set `limit` to a value from 0 to 10000. | | `400` | `You have exceeded the limit amount allowed for selected fields (37 fields).` | The query selects more than 37 fields. `ts` counts as a field; the output of `aggregate` does not. | Select 37 fields or fewer. | | `400` | `The query has reached a system limit. Please adjust your query and try again.` | On `workloadEvents`, the query selects 37 fields. On `functionConsoleEvents` and `cellsConsoleEvents`, the time window is 7 days long. | On `workloadEvents`, select 36 fields or fewer. On the console datasets, shorten the time window; a 1-hour window is accepted. | | `500` | `An error occured while performing the requested operation.: Limit for rows or bytes to read exceeded, max rows: 10.00 billion, current rows: billion` | The query reads more than 10 billion rows. This happens on a long time window, such as 7 days, with no other filter. | Shorten the time window, or add filter arguments that narrow the query. | On `workloadEvents`, 38 selected fields return the 37-field message, and 37 selected fields return the system limit message. This query to `https://api.azion.com/v4/events/graphql` counts the `functionConsoleEvents` records of a 7-day window: ```graphql query { functionConsoleEvents(limit: 1, filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} }, aggregate: { count: rows }) { count } } ``` The API refuses the window with `400`: ```json { "detail": "The query has reached a system limit. Please adjust your query and try again." } ``` --- ## Access and rate errors Access and rate errors depend on the account and on the request volume, not on the query: | Status | `detail` | Cause | Fix | | ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------- | | `404` | `The following resource could not be found.` | The account, identified by its `client_id`, is not allowed to access the requested API resource. | Query an endpoint the account has access to. | | `429` | `You have reached the request rate limit!` | The requests from one IP address passed the request rate limit. | Send fewer requests from the IP address. | --- ## Related resources - [GraphQL API limits](/en/documentation/devtools/graphql/limits.md): The row, field, and time-window bounds that the limit errors enforce. - [Troubleshoot the GraphQL API](/en/documentation/devtools/graphql/troubleshooting.md): The symptoms a refused or empty query shows, with the fix for each one. - [Datasets and query arguments](/en/documentation/devtools/graphql/features.md): The datasets of each endpoint and the arguments and filter fields each one accepts. - [Personal tokens](/en/documentation/fundamentals/personal-tokens.md): The tokens that the `Authorization` header carries, and how they expire.