# Respostas de erro Quando a [GraphQL API](/pt-br/documentacao/devtools/graphql/) recusa uma requisição, ela retorna um código de status HTTP e um corpo JSON com uma chave, `detail`, que contém a mensagem. O corpo nunca traz um array `errors` do GraphQL. Os erros se dividem em quatro grupos: de autenticação, de construção da query, de limite de query e de acesso e taxa de requisições. Uma requisição a um caminho que não é um dos cinco endpoints GraphQL retorna `204` com o corpo vazio, não uma mensagem de erro. --- ## Formato do erro Todo corpo de erro tem o mesmo formato. Esta query vai para `https://api.azion.com/v4/metrics/graphql` com o header `Authorization: Bearer [TOKEN VALUE]`, que a API não aceita: ```graphql { __typename } ``` A API retorna `401` com a mensagem em `detail`: ```json { "detail": "Authentication credentials were not provided." } ``` As tabelas a seguir mostram cada valor de `detail` com o texto exato da mensagem. Uma mensagem que ocupa várias linhas no corpo aparece em uma única linha. --- ## Erros de autenticação Os erros de autenticação retornam `401`. A API aceita uma única forma de header em todo endpoint, `Authorization: Token [TOKEN VALUE]`: | Status | `detail` | Causa | Correção | | ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------- | | `401` | `Authentication credentials were not provided.` | A requisição não tem o header `Authorization`, ou o header usa `Bearer` em vez de `Token`. | Envie o header `Authorization: Token [TOKEN VALUE]`. | | `401` | `Invalid Token` | O header `Authorization` traz um valor que não é um token válido. | Envie um personal token válido no header. | | `401` | `The authorization token has expired.` | O token no header expirou. | Envie um token que não tenha expirado. | --- ## Erros de construção da query Os erros de construção da query retornam `400`. A API verifica a query em relação ao schema do endpoint e às regras de cada argumento. Quando o nome de um campo, dataset ou argumento é próximo de um nome válido, a mensagem termina com `Did you mean`, seguido dos nomes válidos: | Status | `detail` | Causa | Correção | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | `To execute queries it is mandatory to provide the desired time interval.` | Uma query ao endpoint de métricas ou de eventos não tem uma janela de tempo em `filter`. | Adicione `tsRange`, ou `tsGt` e `tsLt`, a `filter`. | | `400` | `The start and end dates must have the same timezone.` | Um limite da janela de tempo tem um sufixo de fuso horário, como `Z`, e o outro não tem. | Escreva os dois limites sem sufixo, que a API lê como UTC, como `2026-10-03T13:00:00`. Os dois limites com o mesmo offset, como `-03:00`, também são aceitos e convertidos para UTC. | | `400` | `The query includes fields that require grouping. Please ensure all non-aggregated fields are included in groupBy argument.` | A query seleciona um campo de medida, como `requests`, diretamente. | Leia a medida por meio de `aggregate`, como `aggregate: { sum: requests }`, e selecione a saída da função, `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.` | A query usa `resample` sem `ts` em `groupBy`. | Adicione `ts` a `groupBy` e aos campos selecionados, ou remova `resample`. | | `400` | `Cannot query field "requestz" on type "WorkloadMetricsAggregatedFieldsLogType". Did you mean "requests", "requestTime", "requestMethod", "requestLength" or "requestsTotal"?` | A query seleciona um campo que o dataset não tem. A mensagem nomeia o campo e o tipo do dataset. | Selecione um campo que o dataset lista, como um dos nomes que a mensagem sugere. | | `400` | `Cannot query field "workloadMetric" on type "Query". Did you mean "workloadMetrics" or "workloadBreakdownMetrics"?` | O nome do dataset não existe no endpoint. | Corrija o nome do dataset. | | `400` | `Cannot query field "workloadEvents" on type "Query". Did you mean "workloadMetrics" or "workloadBreakdownMetrics"?` | O dataset pertence a outro endpoint. Aqui, a query envia um dataset de eventos ao endpoint de métricas. | Envie a query ao endpoint que serve o dataset, aqui `https://api.azion.com/v4/events/graphql`. | | `400` | `Unknown argument "limits" on field "workloadMetrics" of type "Query". Did you mean "limit"?` | A query passa um argumento que o dataset não aceita. Aqui, o nome está escrito errado. | Corrija o nome do argumento. | | `400` | `Unknown argument "resample" on field "workloadEvents" of type "Query".` | A query usa `resample` em um dataset de eventos. Apenas datasets de métricas aceitam `resample`. | Remova `resample` ou consulte um dataset de métricas. | | `400` | `Argument "groupBy" has invalid value [ts, invocationsss]. In element #1: Expected type "WorkloadMetricsGroupByFields", found invocationsss.` | Um valor em `groupBy` não é um campo pelo qual o dataset pode agrupar. A mensagem conta os elementos a partir de zero. | Substitua o valor por um campo que o dataset lista para `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` nomeia um campo que o dataset não tem. A mensagem repete o filtro inteiro. | Use um campo de filtro que o dataset lista. | | `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".` | Um valor de filtro tem o tipo errado. Aqui, uma string foi passada para um campo inteiro. | Passe o valor no tipo que a mensagem nomeia, aqui `statusEq: 200`. | | `400` | `Syntax Error GraphQL (2:109) Expected Name, found {` | A query não é GraphQL válido. A mensagem informa a linha e a coluna do erro e, em seguida, um trecho da query. | Corrija a query na linha e na coluna que a mensagem nomeia. | Uma janela de tempo cujo `begin` é posterior ao seu `end` não é recusada: a API retorna `200` com um array vazio. Esta query para `https://api.azion.com/v4/metrics/graphql` não tem o `)` que fecha os argumentos de `workloadMetrics`: ```graphql query { workloadMetrics(limit: 3, filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} } { ts } } ``` A API retorna `400`, e `detail` traz a posição, um trecho da query e um circunflexo (`^`) sob a coluna do erro: ```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" } ``` --- ## Erros de limite de query Os erros de limite de query interrompem uma query que pede mais linhas, campos ou dados do que uma query pode ler. Os limites em si estão em [Limites da GraphQL API](/pt-br/documentacao/devtools/graphql/limites/): | Status | `detail` | Causa | Correção | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `The value for the query limit is invalid (must be between 0 to 10000 rows).` | `limit` está fora do intervalo de 0 a 10.000, como `10001` ou `-1`. | Defina `limit` com um valor de 0 a 10.000. | | `400` | `You have exceeded the limit amount allowed for selected fields (37 fields).` | A query seleciona mais de 37 campos. `ts` conta como campo; a saída de `aggregate`, não. | Selecione 37 campos ou menos. | | `400` | `The query has reached a system limit. Please adjust your query and try again.` | Em `workloadEvents`, a query seleciona 37 campos. Em `functionConsoleEvents` e `cellsConsoleEvents`, a janela de tempo tem 7 dias. | Em `workloadEvents`, selecione 36 campos ou menos. Nos datasets de console, encurte a janela de tempo; uma janela de 1 hora é aceita. | | `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` | A query lê mais de 10 bilhões de linhas. Isso acontece em uma janela de tempo longa, como 7 dias, sem outro filtro. | Encurte a janela de tempo ou adicione argumentos de filtro que restrinjam a query. | Em `workloadEvents`, 38 campos selecionados retornam a mensagem de 37 campos, e 37 campos selecionados retornam a mensagem de limite do sistema. Esta query para `https://api.azion.com/v4/events/graphql` conta os registros de `functionConsoleEvents` de uma janela de 7 dias: ```graphql query { functionConsoleEvents(limit: 1, filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} }, aggregate: { count: rows }) { count } } ``` A API recusa a janela com `400`: ```json { "detail": "The query has reached a system limit. Please adjust your query and try again." } ``` --- ## Erros de acesso e de taxa de requisições Os erros de acesso e de taxa de requisições dependem da conta e do volume de requisições, não da query: | Status | `detail` | Causa | Correção | | ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | `404` | `The following resource could not be found.` | A conta, identificada pelo seu `client_id`, não tem permissão para acessar o recurso da API solicitado. | Consulte um endpoint ao qual a conta tem acesso. | | `429` | `You have reached the request rate limit!` | As requisições de um endereço IP ultrapassaram o limite de taxa de requisições. | Envie menos requisições a partir do endereço IP. | --- ## Recursos relacionados - [Limites da GraphQL API](/pt-br/documentacao/devtools/graphql/limites.md): Os limites de linhas, campos e janela de tempo que os erros de limite aplicam. - [Solucionar problemas da GraphQL API](/pt-br/documentacao/devtools/graphql/solucao-de-problemas.md): Os sintomas que uma query recusada ou vazia mostra, com a correção de cada um. - [Datasets e argumentos de query](/pt-br/documentacao/devtools/graphql/recursos.md): Os datasets de cada endpoint e os argumentos e campos de filtro que cada um aceita. - [Personal tokens](/pt-br/documentacao/fundamentos/personal-tokens.md): Os tokens que o header `Authorization` carrega e como eles expiram.