Troubleshoot the GraphQL API

A GraphQL API request can fail with a 401 or a 204, a query can fail with a 400 that names the problem, and a query can return no rows. Authentication and endpoint errors come first, then refused queries, empty results, and the GraphiQL Playground. Every error the API returns is a JSON object with a single detail key.

A request returns 401 with Authentication credentials were not provided

A request to a GraphQL API endpoint returns HTTP 401 with this body:

The request has no Authorization header, or it sends the token with the Bearer scheme. The API treats a Bearer header as an absent header.

• Send the Token scheme: add the header Authorization: Token [TOKEN VALUE] to every request, with the value of your personal token.
• Check the header name: the header is Authorization, and the scheme word Token comes before the value, separated by a space.

The query { __typename } then returns HTTP 200 with "__typename": "Query".

A request returns 401 with Invalid Token

A request with an Authorization: Token header returns HTTP 401 with this body:

The header uses the right scheme, but the API does not accept its value as a personal token.

• Copy the whole token: paste the full value of the personal token after the word Token and one space, with no quotes.
• Create another personal token: if you no longer have the value, create a personal token in Azion Console. For the steps, refer to How to manage a personal token.

The request then returns HTTP 200 with a data object.

A request returns 204 with an empty body

A POST request with a valid token returns HTTP 204 and no body, not an error.

The URL is not one of the GraphQL API endpoints. An unknown path under https://api.azion.com/v4/ answers 204, not 404.

• Use one of the five endpoints: each endpoint serves one data family. Send the query to the endpoint that holds its dataset:

The request then returns HTTP 200 with a data object, or a 400 that names the problem in the query. For the datasets of each endpoint, refer to Datasets and query arguments.

A query fails with Cannot query field workloadEvents on type Query

A query on an events dataset, such as workloadEvents, returns HTTP 400 with this body:

The query went to the metrics endpoint, which serves only Metrics datasets. The same message names a dataset whose name is misspelled, such as workloadMetric.

• Send events queries to the events endpoint: post workloadEvents and the other events datasets to https://api.azion.com/v4/events/graphql.
• Check the dataset name: the Did you mean list of the message names the datasets that endpoint serves.

This query, sent to the events endpoint, returns the latest requests of a 7-day window:

The response holds one object per request. It is cut after the third of 5 rows:

The query returns HTTP 200 with the records of the window.

A query fails with The query has reached a system limit

An events query returns HTTP 400 with this body:

The query exceeds a bound of the events endpoint. Two causes return this message: 37 or more selected fields on workloadEvents, or a 7-day window on functionConsoleEvents.

• Select at most 36 fields on workloadEvents: remove fields until the query selects 36 or fewer. On a Metrics dataset, the limit is 37 fields. The 38th field returns You have exceeded the limit amount allowed for selected fields (37 fields).
• Shorten the window on console events: query functionConsoleEvents over a shorter window, such as one hour. The deprecated cellsConsoleEvents returns the same error; use functionConsoleEvents.

The query then returns HTTP 200. For every bound a query runs within, refer to GraphQL API limits.

A query fails with The query includes fields that require grouping

A Metrics query returns HTTP 400 with this body:

The query selects a measure, such as requests, without aggregating it. A measure goes in the aggregate argument, and the response returns its result in a field named after the function.

• Aggregate the measure: move the measure into aggregate, such as aggregate: { sum: requests }, and select sum in place of requests.
• Group by the other fields: list every selected field that is not an aggregate in groupBy.

This query sums the requests of a 7-day window per time bucket:

The response holds one row per bucket and is cut after the third row:

The query returns HTTP 200 with one sum per group.

A resample query fails with Query syntax error

A query with a resample argument returns HTTP 400 with this body:

The groupBy argument of the query does not hold ts, which every resample query requires.

• Group by ts: add ts to groupBy, and select ts and every other groupBy field.
• Resample a Metrics dataset: resample exists only on Metrics datasets. On an events dataset, the API returns Unknown argument "resample".

This query resamples the requests of a 7-day window to 10 points:

The response holds one row per point. It is cut after the third of 11 rows:

The query returns HTTP 200 with the resampled points. For the resample functions, refer to Datasets and query arguments.

A query fails with The start and end dates must have the same timezone

A query returns HTTP 400 with this body:

One bound of the time window carries a timezone and the other does not, such as Z on begin only.

• Use the same offset on both bounds: write both dates with the same offset, such as -03:00, or both without one. The API converts both to UTC.

This query reads one hour with the -03:00 offset on both bounds:

The response returns the buckets in UTC:

The query returns HTTP 200 with timestamps in UTC.

A query returns an empty array

A query returns HTTP 200, but the dataset array holds no rows:

No row matches the window and the filters. The API returns no error when the window is reversed or holds no data.

• Check the order of the bounds: begin must come before end. A reversed window returns an empty array.
• Move the window inside the retention: events records are kept about 7 days, so a wider window returns nothing for the part outside it. workloadBreakdownMetrics keeps 90 days of data. For the retention of each dataset, refer to How the GraphQL API works.
• Replace copied dates: an example query with dates from an earlier year returns an empty array. Set the window to a period with traffic.
• Check that the account has data: a dataset with no traffic on the account returns an empty array.

The query returns rows once the window holds data that matches the filters.

The GraphiQL Playground returns Authentication credentials were not provided

An endpoint URL opened in a browser shows HTTP 401 with this body, not the GraphiQL Playground:

The browser request carries no session and no token.

• Log in to Azion Console first: log in to Azion Console in the same browser, then open the endpoint URL.
• Open an endpoint URL: the Playground runs on the five endpoint URLs, such as https://api.azion.com/v4/metrics/graphql. The API root, https://api.azion.com/v4, opens the REST API reference.
• Send the token header: a GET request with Accept: text/html and Authorization: Token [TOKEN VALUE] returns GraphiQL with HTTP 200.

The endpoint URL then opens GraphiQL. For the Playground, refer to GraphiQL Playground.

Related resources