Error responses
Look up the status codes and messages the GraphQL API returns when it refuses a request, with the cause and the fix for each one.
When the GraphQL API 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:
The API returns 401 with the message in detail:
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:
The API returns 400, and detail carries the position, an excerpt of the query, and a caret under the column of the error:
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:
| 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: <n> 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:
The API refuses the window with 400:
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. |