# Solucionar problemas da GraphQL API Uma requisição à [GraphQL API](/pt-br/documentacao/devtools/graphql/) pode falhar com `401` ou `204`, uma query pode falhar com um `400` que indica o problema e uma query pode não retornar nenhuma linha. Os erros de autenticação e de endpoint vêm primeiro. Em seguida vêm as queries recusadas, os resultados vazios e o GraphiQL Playground. Todo erro que a API retorna é um objeto JSON com uma única chave, `detail`. --- ## Uma requisição retorna 401 com Authentication credentials were not provided Uma requisição a um endpoint da GraphQL API retorna HTTP `401` com este corpo: ```json { "detail": "Authentication credentials were not provided." } ``` A requisição não tem o header `Authorization`, ou envia o token com o esquema `Bearer`. A API trata um header `Bearer` como um header ausente. - **Envie o esquema Token**: adicione o header `Authorization: Token [TOKEN VALUE]` a toda requisição, com o valor do seu personal token. - **Confira o nome do header**: o header é `Authorization`, e a palavra do esquema, `Token`, vem antes do valor, separada dele por um espaço. A query `{ __typename }` então retorna HTTP `200` com `"__typename": "Query"`. --- ## Uma requisição retorna 401 com Invalid Token Uma requisição com um header `Authorization: Token` retorna HTTP `401` com este corpo: ```json { "detail": "Invalid Token" } ``` O header usa o esquema correto, mas a API não aceita o valor dele como um personal token. - **Copie o token inteiro**: cole o valor completo do personal token depois da palavra `Token` e de um espaço, sem aspas. - **Crie outro personal token**: se você não tem mais o valor, crie um personal token no Azion Console. Para os passos, consulte [Como criar um personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/). A requisição então retorna HTTP `200` com um objeto `data`. --- ## Uma requisição retorna 204 com o corpo vazio Uma requisição `POST` com um token válido retorna HTTP `204` sem corpo, em vez de um erro. A URL não é um dos endpoints da GraphQL API. Um caminho desconhecido em `https://api.azion.com/v4/` responde `204`, não `404`. - **Use um dos cinco endpoints**: cada endpoint atende uma família de dados. Envie a query para o endpoint que contém o dataset dela: ```text https://api.azion.com/v4/metrics/graphql https://api.azion.com/v4/events/graphql https://api.azion.com/v4/billing/graphql https://api.azion.com/v4/accounting/graphql https://api.azion.com/v4/consumption/graphql ``` A requisição então retorna HTTP `200` com um objeto `data`, ou um `400` que indica o problema na query. Para os datasets de cada endpoint, consulte [Datasets e argumentos de query](/pt-br/documentacao/devtools/graphql/recursos/). --- ## Uma query falha com Cannot query field workloadEvents on type Query Uma query em um dataset de eventos, como `workloadEvents`, retorna HTTP `400` com este corpo: ```json { "detail": "Cannot query field \"workloadEvents\" on type \"Query\". Did you mean \"workloadMetrics\" or \"workloadBreakdownMetrics\"?" } ``` A query foi enviada para o endpoint de métricas, que atende apenas datasets de Metrics. A mesma mensagem aparece para um dataset com o nome escrito errado, como `workloadMetric`. - **Envie queries de eventos para o endpoint de eventos**: envie `workloadEvents` e os outros datasets de eventos para `https://api.azion.com/v4/events/graphql`. - **Confira o nome do dataset**: a lista `Did you mean` da mensagem indica os datasets que aquele endpoint atende. Esta query, enviada para o endpoint de eventos, retorna as requisições mais recentes de uma janela de 7 dias: ```graphql query { workloadEvents( limit: 5 filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} } orderBy: [ts_DESC] ) { ts host status requestUri } } ``` A resposta contém um objeto por requisição. Ela foi cortada depois da terceira de 5 linhas: ```json { "data": { "workloadEvents": [ { "ts": "2026-10-03T13:34:44Z", "host": "www.example.com", "status": 200, "requestUri": "/" }, { "ts": "2026-10-03T13:16:33Z", "host": "www.example.com", "status": 200, "requestUri": "/" }, { "ts": "2026-10-03T12:53:40Z", "host": "www.example.com", "status": 200, "requestUri": "/" }, … ] } } ``` A query retorna HTTP `200` com os registros da janela. --- ## Uma query falha com The query has reached a system limit Uma query de eventos retorna HTTP `400` com este corpo: ```json { "detail": "The query has reached a system limit. Please adjust your query and try again." } ``` A query ultrapassa um limite do endpoint de eventos. Duas causas retornam essa mensagem: 37 ou mais campos selecionados em `workloadEvents`, ou uma janela de 7 dias em `functionConsoleEvents`. - **Selecione no máximo 36 campos em workloadEvents**: remova campos até a query selecionar 36 ou menos. Em um dataset de Metrics, o limite é de 37 campos. O 38º campo retorna `You have exceeded the limit amount allowed for selected fields (37 fields).` - **Encurte a janela nos eventos de console**: consulte `functionConsoleEvents` em uma janela mais curta, como uma hora. O dataset `cellsConsoleEvents`, obsoleto, retorna o mesmo erro; use `functionConsoleEvents`. A query então retorna HTTP `200`. Para todos os limites dentro dos quais uma query é executada, consulte [Limites da GraphQL API](/pt-br/documentacao/devtools/graphql/limites/). --- ## Uma query falha com The query includes fields that require grouping Uma query de Metrics retorna HTTP `400` com este corpo: ```json { "detail": "The query includes fields that require grouping. Please ensure all non-aggregated fields are included in groupBy argument." } ``` A query seleciona uma medida, como `requests`, sem agregá-la. Uma medida vai no argumento `aggregate`, e a resposta retorna o resultado dela em um campo com o nome da função. - **Agregue a medida**: mova a medida para `aggregate`, como `aggregate: { sum: requests }`, e selecione `sum` no lugar de `requests`. - **Agrupe pelos outros campos**: liste em `groupBy` todo campo selecionado que não é um agregado. Esta query soma as requisições de uma janela de 7 dias por intervalo de tempo: ```graphql query { workloadMetrics(limit: 10000, filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} }, aggregate: { sum: requests }, groupBy: [ts]) { ts sum } } ``` A resposta contém uma linha por intervalo e é cortada depois da terceira linha: ```json { "data": { "workloadMetrics": [ { "ts": "2026-10-02T20:00:00Z", "sum": 76 }, { "ts": "2026-10-03T14:00:00Z", "sum": 1 }, { "ts": "2026-10-02T03:00:00Z", "sum": 2 }, … ] } } ``` A query retorna HTTP `200` com um `sum` por grupo. --- ## Uma query de resample falha com Query syntax error Uma query com um argumento `resample` retorna HTTP `400` com este corpo: ```json { "detail": "\n Query syntax error. In resample queries, you must provide the timestamp (ts) field in\n the group_by parameter and you must include the group_by fields in the selected fields to return data.\n To query data without resampling, remove the resample parameter from the query.\n" } ``` O argumento `groupBy` da query não contém `ts`, que toda query de resample exige. - **Agrupe por ts**: adicione `ts` a `groupBy` e selecione `ts` e todos os outros campos de `groupBy`. - **Faça o resample de um dataset de Metrics**: `resample` existe apenas em datasets de Metrics. Em um dataset de eventos, a API retorna `Unknown argument "resample"`. Esta query faz o resample das requisições de uma janela de 7 dias para 10 pontos: ```graphql query { workloadMetrics( limit: 10000 resample: { function: mean, points: 10 } filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} } aggregate: { sum: requests } groupBy: [ts] orderBy: [ts_ASC] ) { ts sum } } ``` A resposta contém uma linha por ponto. Ela foi cortada depois da terceira de 11 linhas: ```json { "data": { "workloadMetrics": [ { "ts": "2026-09-26T16:00:00Z", "sum": 2.0 }, { "ts": "2026-09-27T08:00:00Z", "sum": 2.125 }, { "ts": "2026-09-28T00:00:00Z", "sum": 3.6875 }, … ] } } ``` A query retorna HTTP `200` com os pontos após o resample. Para as funções de resample, consulte [Datasets e argumentos de query](/pt-br/documentacao/devtools/graphql/recursos/). --- ## Uma query falha com The start and end dates must have the same timezone Uma query retorna HTTP `400` com este corpo: ```json { "detail": "The start and end dates must have the same timezone." } ``` Um limite da janela de tempo tem um fuso horário e o outro não tem, como `Z` apenas em `begin`. - **Use o mesmo offset nos dois limites**: escreva as duas datas com o mesmo offset, como `-03:00`, ou as duas sem offset. A API converte as duas para UTC. Esta query lê uma hora com o offset `-03:00` nos dois limites: ```graphql query { workloadMetrics(limit: 3, filter: { tsRange: { begin: "2026-10-03T10:00:00-03:00", end: "2026-10-03T11:00:00-03:00" } }, aggregate: { sum: requests }, groupBy: [ts], orderBy: [ts_ASC]) { ts sum } } ``` A resposta retorna os intervalos em UTC: ```json { "data": { "workloadMetrics": [ { "ts": "2026-10-03T13:16:00Z", "sum": 1 }, { "ts": "2026-10-03T13:34:00Z", "sum": 1 } ] } } ``` A query retorna HTTP `200` com os timestamps em UTC. --- ## Uma query retorna um array vazio Uma query retorna HTTP `200`, mas o array do dataset não contém nenhuma linha: ```json { "data": { "workloadMetrics": [] } } ``` Nenhuma linha corresponde à janela e aos filtros. A API não retorna erro quando a janela está invertida ou não contém dados. - **Confira a ordem dos limites**: `begin` precisa vir antes de `end`. Uma janela invertida retorna um array vazio. - **Mova a janela para dentro da retenção**: os registros de eventos são mantidos por cerca de 7 dias, então uma janela maior não retorna nada para a parte que fica fora desse período. `workloadBreakdownMetrics` mantém 90 dias de dados. Para a retenção de cada dataset, consulte [Como a GraphQL API funciona](/pt-br/documentacao/devtools/graphql/visao-geral/). - **Substitua datas copiadas**: uma query de exemplo com datas de um ano anterior retorna um array vazio. Defina a janela para um período com tráfego. - **Confira se a conta tem dados**: um dataset sem tráfego na conta retorna um array vazio. A query retorna linhas assim que a janela contém dados que correspondem aos filtros. --- ## O GraphiQL Playground retorna Authentication credentials were not provided Uma URL de endpoint aberta em um navegador mostra HTTP `401` com este corpo, em vez do GraphiQL Playground: ```json {"detail": "Authentication credentials were not provided."} ``` A requisição do navegador não traz nenhuma sessão nem nenhum token. - **Faça login no Azion Console primeiro**: faça login no [Azion Console](https://console.azion.com/) no mesmo navegador e então abra a URL do endpoint. - **Abra uma URL de endpoint**: o Playground é executado nas cinco URLs de endpoint, como `https://api.azion.com/v4/metrics/graphql`. A raiz da API, `https://api.azion.com/v4`, abre a referência da REST API. - **Envie o header do token**: uma requisição `GET` com `Accept: text/html` e `Authorization: Token [TOKEN VALUE]` retorna o GraphiQL com HTTP `200`. A URL do endpoint então abre o GraphiQL. Para o Playground, consulte [GraphiQL Playground](/pt-br/documentacao/devtools/graphql/playground-graphql/). --- ## Recursos relacionados - [Respostas de erro](/pt-br/documentacao/devtools/graphql/mensagens-erro.md): Todos os códigos de status e mensagens que a API retorna, com a causa de cada um. - [Limites da GraphQL API](/pt-br/documentacao/devtools/graphql/limites.md): Os limites de linhas, de campos e de janela de tempo que vários desses erros aplicam. - [Como a GraphQL API funciona](/pt-br/documentacao/devtools/graphql/visao-geral.md): Os endpoints, os datasets, as janelas de tempo e a retenção dos quais as correções dependem. - [Primeiros passos com a GraphQL API](/pt-br/documentacao/devtools/graphql/primeiros-passos.md): Crie um personal token e execute uma primeira query no GraphiQL ou na API.