Limites de taxas e limites de consultas para a API GraphQL

Limite da taxa primária

A API do GraphQL atribui pontos a cada consulta e limita os pontos que você pode usar dentro de um período de tempo específico. Esse limite ajuda a evitar abusos e ataques de negação de serviço, além de garantir que a API permaneça disponível para todos os usuários.

A API REST também tem um limite de taxa primária separado. Para saber mais, confira Limites de taxa para a API REST.

Em geral, é possível calcular o limite de taxa primária da API GraphQL com base em seu método de autenticação.

Para usuários: 5.000 pontos por hora por usuário. Isso inclui solicitações feitas com um personal access token, bem como solicitações feitas por um GitHub App ou OAuth app em nome de um usuário que autorizou o aplicativo. O limite de taxa será mais alto (15.000 solicitações por hora) se as solicitações forem feitas em seu nome por um GitHub App pertencente a uma organização do GitHub Enterprise Cloud. Do mesmo modo, as solicitações realizadas em seu nome por um OAuth app pertencente ou aprovado por uma organização do GitHub Enterprise Cloud terão um limite de taxa mais alto (de 15.000 solicitações por hora) se você for membro da organização GitHub Enterprise Cloud.
Para instalações do GitHub App não em uma GitHub Enterprise Cloud organização ou empresa: 5 mil pontos por hora por instalação. As instalações com mais de 20 repositórios recebem outros 50 pontos por hora para cada repositório. Instalações que estão em uma organização que possui mais de 20 usuários recebem outros 50 pontos por hora para cada usuário. O limite de pontos não pode ser aumentado para além de 12.500 pontos por hora. O limite de taxa para tokens de acesso de usuário (em oposição aos tokens de acesso de instalação) é ditado pelo limite de taxa principal para usuários.
Para instalações do GitHub App em uma GitHub Enterprise Cloud organização ou empresa: 10 mil pontos por hora por instalação. O limite de taxa para tokens de acesso de usuário (em oposição aos tokens de acesso de instalação) é ditado pelo limite de taxa principal para usuários.
Para OAuth apps: 5.000 pontos por hora ou 10.000 pontos por hora se o aplicativo pertencer a uma organização GitHub Enterprise Cloud. Isso só se aplica quando o aplicativo usa a ID do cliente e o segredo do cliente para solicitar dados públicos. Os limites de taxa primária para os tokens de acesso OAuth gerados por um OAuth app são determinados pelos limites de taxa primária para usuários autenticados.
Para GITHUB_TOKEN em fluxos de trabalho do GitHub Actions: 1.000 pontos por hora por repositório. Para solicitações a recursos que pertencem a uma conta corporativa no GitHub.com, o limite é de 15.000 pontos por hora por repositório.

Você pode verificar o valor de ponto de uma consulta ou calcular o valor de ponto esperado, conforme descrito nas seções a seguir. A fórmula de cálculo dos pontos e o limite da taxa estão sujeitos a alterações.

Verificar o status do limite de taxa primário

Você pode usar os cabeçalhos enviados em cada resposta para determinar o status atual do limite de taxa primária.

Nome do cabeçalho	Descrição
`x-ratelimit-limit`	O número máximo de pontos que você pode usar por hora
`x-ratelimit-remaining`	O número de pontos restantes na janela atual de limite de taxa
`x-ratelimit-used`	O número de pontos que você usou na janela do limite de taxa atual
`x-ratelimit-reset`	O tempo em que a janela atual de limite de taxa é redefinida em segundos de época UTC
`x-ratelimit-resource`	O recurso de limite de taxa em que a solicitação feita foi incluída. Para solicitações do GraphQL, isso sempre será `graphql`.

Também é possível consultar o objeto rateLimit para verificar o limite de taxa. Quando possível, use os cabeçalhos de resposta do limite de taxa em vez de chamar a API para verificá-lo.

query {
  viewer {
    login
  }
  rateLimit {
    limit
    remaining
    used
    resetAt
  }
}

Campo	Descrição
`limit`	O número máximo de pontos que você pode usar por hora
`remaining`	O número de pontos restantes na janela atual de limite de taxa
`used`	O número de pontos que você usou na janela do limite de taxa atual
`resetAt`	O tempo em que a janela atual de limite de taxa é redefinida em segundos de época UTC

Retornando o valor de pontuação de uma consulta

Você pode retornar o valor de ponto de uma consulta consultando o cost``rateLimit campo no objeto:

query {
  viewer {
    login
  }
  rateLimit {
    cost
  }
}

Prevendo o valor de pontuação de uma consulta

Você também pode calcular aproximadamente o valor do ponto de uma consulta antes de fazer a consulta.

Adicione o número de solicitações necessárias para atender cada conexão única na chamada. Suponha que cada solicitação atingirá os limites dos argumentos first e last.
Divida o número por 100 e arredonde o resultado para o número inteiro mais próximo para obter o valor total agregado final. Esta etapa normaliza números grandes.

Observação

O valor mínimo de ponto de uma chamada para a API GraphQL é 1.

Aqui está um exemplo de consulta e cálculo de pontuação:

query {
  viewer {
    login
    repositories(first: 100) {
      edges {
        node {
          id

          issues(first: 50) {
            edges {
              node {
                id

                labels(first: 60) {
                  edges {
                    node {
                      id
                      name
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Esta consulta exige que 5,101 solicitações sejam atendidas:

Embora estejamos retornando 100 repositórios, a API precisa se conectar à conta do visualizador uma vez para obter a lista de repositórios. Portanto, as solicitações de repositórios = 1
Embora estejamos retornando 50 problemas, a API precisa se conectar a cada um dos 100 repositórios para obter a lista de problemas. Portanto, as solicitações de problemas = 100
Embora estejamos retornando 60 rótulos, a API precisa se conectar a cada um dos cinco mil possíveis problemas totais para obter a lista de rótulos. Portanto, as solicitações de rótulos = 5.000
Total = 5.101

Dividindo isso por 100 e arredondando o resultado, obtemos a pontuação final da consulta: 51

Limites de taxa secundária

Além dos limites de taxa primária, GitHub impõe limites de taxa secundários para evitar abusos e manter a API disponível para todos os usuários.

Você pode encontrar um limite de taxa secundário se:

Enviar muitas solicitações simultâneas. Não são permitidas mais de 100 solicitações simultâneas. Esse limite é compartilhado entre a API REST e a API GraphQL.
Enviar muitas solicitações a um único endpoint por minuto. Não são permitidos mais de 900 pontos por minuto para pontos de extremidade da API REST e não mais de 2.000 pontos por minuto para o ponto de extremidade da API GraphQL. Para obter mais informações sobre pontos, confira Calcular pontos para o limite de taxa secundária.
Enviar muitas solicitações por minuto. Não é permitido mais do que 90 segundos de tempo de CPU por 60 segundos de tempo real. Não mais do que 60 segundos desse tempo de CPU pode ser para a API GraphQL. Você pode estimar aproximadamente o tempo de CPU medindo o tempo total de resposta para suas solicitações de API.
Fazer muitas solicitações que consomem recursos de computação excessivos em um curto período de tempo.
Produzir conteúdo em excesso na GitHub em um curto período de tempo. Em geral, não são permitidas mais de 80 solicitações de geração de conteúdo por minuto e não mais de 500 solicitações de geração de conteúdo por hora. Alguns endpoints têm limites mais baixos para criação de conteúdo. Os limites de criação de conteúdo incluem ações executadas na interface da Web GitHub, bem como por meio da API REST e da API GraphQL.
Faça muitas solicitações de token de acesso OAuth em um curto período de tempo. Não são permitidos mais de 2.000 pedidos de token de acesso OAuth por hora para GitHub Apps e OAuth apps.

Estes limites de taxas secundárias estão sujeitos a alterações sem aviso prévio. Você também pode encontrar um limite de taxa secundário por motivos não revelados.

Cálculo de pontos para o limite da taxa secundária

Alguns limites de taxa secundária são determinados pelos valores de ponto das solicitações. Para solicitações do GraphQL, esses valores de pontos são separados dos cálculos dos valores de pontos para o limite de taxa principal.

Solicitar	Pontos
Solicitações do GraphQL sem mutações	1
Solicitações GraphQL com mutações	5
A maioria das solicitações da API REST `GET`, `HEAD` e `OPTIONS`	1
A maioria das solicitações à API REST `POST`, `PATCH`, `PUT` ou `DELETE`	5

Alguns pontos de extremidade da API REST têm um custo de ponto diferente que não é compartilhado publicamente.

Excedendo o limite de taxa

Se você exceder o limite de taxa principal, o status da resposta ainda será 200, mas você receberá uma mensagem de erro e o x-ratelimit-remaining valor do cabeçalho será 0. Não repita a solicitação até depois do horário especificado no cabeçalho de x-ratelimit-reset.

Se exceder uma limitação de fluxo secundária, receberá uma resposta 200 ou 403 e uma mensagem de erro indicando que você excedeu uma limitação secundária. Se o cabeçalho de resposta retry-after estiver presente, você não deverá repetir sua solicitação até que esse número de segundos tenha decorrido. Se o cabeçalho de x-ratelimit-remaining for 0, você não deverá repetir sua solicitação até depois do horário, em segundos de período UTC, especificado pelo cabeçalho de x-ratelimit-reset. Caso contrário, aguarde pelo menos um minuto antes de tentar novamente. Se sua solicitação continuar falhando devido a uma limitação de fluxo secundário, aguarde um período de tempo exponencialmente crescente entre as tentativas e lance um erro após um número específico de tentativas.

Continuar a fazer solicitações enquanto você está com limitação de fluxo pode resultar no banimento de sua integração.

Como não ultrapassar o limite de taxa

Para evitar exceder um limite de taxa, você deve pausar pelo menos 1 segundo entre solicitações mutativas e evitar solicitações simultâneas.

Você deve assinar eventos de webhook em vez de sondar a API para obter dados. Para saber mais, confira Documentação de Webhooks.

Também é possível transmitir o log de auditoria para consultar as solicitações à API. Isso pode ajudar a solucionar problemas de integrações que estão excedendo o limite de taxa. Para saber mais, confira Como transmitir o log de auditoria para sua empresa.

Limite do nó

Para passar na validação do schema, todas as chamadas de API do GraphQL devem atender a estes padrões:

Os clientes devem fornecer um argumento first ou last em qualquer conexão.
Os valores de firste last precisam estar entre 1 e 100.
As chamadas individuais não podem solicitar mais de 500 mil nós no total.

Calculando os nós em uma chamada

Estes dois exemplos mostram como calcular os nós totais em uma chamada.

Consulta simples:

query {
  viewer {
    repositories(first: 50) {
      edges {
        repository:node {
          name

          issues(first: 10) {
            totalCount
            edges {
              node {
                title
                bodyHTML
              }
            }
          }
        }
      }
    }
  }
}

Cálculo:

50         = 50 repositories
 +
50 x 10  = 500 repository issues

            = 550 total nodes

Consulta complexa:

query {
  viewer {
    repositories(first: 50) {
      edges {
        repository:node {
          name

          pullRequests(first: 20) {
            edges {
              pullRequest:node {
                title

                comments(first: 10) {
                  edges {
                    comment:node {
                      bodyHTML
                    }
                  }
                }
              }
            }
          }

          issues(first: 20) {
            totalCount
            edges {
              issue:node {
                title
                bodyHTML

                comments(first: 10) {
                  edges {
                    comment:node {
                      bodyHTML
                    }
                  }
                }
              }
            }
          }
        }
      }
    }

    followers(first: 10) {
      edges {
        follower:node {
          login
        }
      }
    }
  }
}

Cálculo:

50              = 50 repositories
 +
50 x 20       = 1,000 pullRequests
 +
50 x 20 x 10 = 10,000 pullRequest comments
 +
50 x 20       = 1,000 issues
 +
50 x 20 x 10 = 10,000 issue comments
 +
10              = 10 followers

                 = 22,060 total nodes

Limites de tempo

Se GitHub levar mais de 10 segundos para processar uma solicitação de API, GitHub encerrará a solicitação e você receberá uma resposta de tempo limite e uma mensagem informando que "Não pudemos responder à sua solicitação a tempo".

GitHub reserva-se o direito de alterar a janela de tempo limite para proteger a velocidade e a confiabilidade da API.

Você pode verificar o status da API GraphQL em githubstatus.com para determinar se o tempo limite ocorre devido a um problema com a API. Também pode tentar simplificar sua solicitação ou tentar sua solicitação mais tarde. Por exemplo, se você estiver solicitando muitos objetos em uma única solicitação, poderá tentar solicitar menos objetos divididos em várias consultas.

Se ocorrer um tempo limite para qualquer uma de suas solicitações de API, pontos adicionais serão deduzidos do limite de taxa principal para a próxima hora para proteger a velocidade e a confiabilidade da API.

Outros limites de recursos

Para proteger a velocidade e a confiabilidade da API, GitHub também impõe outras limitações de recurso. Se a consulta GraphQL consumir muitos recursos, GitHub encerrará a solicitação e retornará resultados parciais, juntamente com um erro que indica que os limites de recursos foram excedidos.

          **Exemplos de consultas que podem exceder os limites de recursos:**

Solicitar milhares de objetos ou relações profundamente aninhadas em uma só consulta.
Usar grandes argumentos first ou last em várias conexões ao mesmo tempo.
Buscar detalhes abrangentes para cada objeto, como todos os comentários, reações e problemas relacionados a cada repositório.

Estratégias de otimização de consulta

Limitar o número de objetos: use valores menores para argumentos first ou last e paginar pelos resultados.
Reduzir a profundidade da consulta: evite solicitar objetos profundamente aninhados, a menos que necessário.
Resultados do filtro: use argumentos para filtrar dados e retornar apenas o que você precisa.
Dividir consultas grandes: divida consultas complexas em várias consultas mais simples.
Solicitar apenas os campos necessários: selecione apenas os campos de que você precisa, em vez de solicitar todos os campos disponíveis.

Seguindo essas estratégias, você pode reduzir a probabilidade de atingir os limites de recursos e melhorar o desempenho e a confiabilidade de suas solicitações de API.

Limites de taxas e limites de consultas para a API GraphQL

Neste artigo