Solucionar problemas do API REST

Erros de limitação de fluxo

GitHub impõe a limitação de fluxo para garantir que a API permaneça disponível para todos os usuários. Para saber mais, confira Limites de taxa para a API REST.

Se você exceder a limitação de fluxo principal, receberá a resposta 403 Forbidden ou 429 Too Many Requests , e o cabeçalho x-ratelimit-remaining será 0. Se exceder uma limitação de fluxo secundária, receberá uma resposta 403 Forbidden ou 429 Too Many Requests e uma mensagem de erro indicando que você excedeu uma limitação secundária.

Se você receber um erro de limitação de fluxo, deverá parar de fazer solicitações temporariamente, de acordo com estas diretrizes:

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 especificado pelo cabeçalho de x-ratelimit-reset. O cabeçalho x-ratelimit-reset está em segundos de época UTC.
Caso contrário, aguarde pelo menos um minuto antes de tentar novamente. Se sua solicitação continuar falhando devido a uma limitação de taxa secundária, aguarde um período de tempo exponencialmente crescente entre as tentativas e lance um erro depois de um número específico de tentativas.

Continuar a fazer solicitações enquanto você está sob limitação de taxa pode resultar no bloqueio da sua integração.

Para obter mais informações sobre como evitar exceder a limitação de fluxo, confira Práticas recomendadas para usar a API REST.

          `404 Not Found` para um recurso existente

Se você fizer uma solicitação para acessar um recurso privado e sua solicitação não for autenticada corretamente, você receberá uma resposta 404 Not Found. GitHub usa uma resposta 404 Not Found em vez de uma resposta 403 Forbidden para evitar a confirmação da existência de repositórios privados.

Se você receber uma resposta 404 Not Found e tiver certeza de que o recurso que está solicitando existe, verifique sua autenticação. Por exemplo:

Se estiver usando um personal access token (classic), certifique-se de que:
- O token tenha os escopos necessários para usar o ponto de extremidade. Para saber mais, confira Escopos para aplicativos OAuth e Gerenciar seus tokens de acesso pessoal.
- O proprietário do token tem todas as permissões necessárias para usar o endpoint. Por exemplo, se um ponto de extremidade só puder ser usado por proprietários da organização, apenas os usuários que forem proprietários da organização afetada poderão usá-lo.
- O token não tenha expirado ou não tenha sido revogado. Para saber mais, confira Vencimento e revogação de token.
Se estiver usando um fine-grained personal access token, certifique-se de que:
- O token tem as permissões necessárias para usar o endpoint. Para obter mais informações sobre as permissões necessárias, confira a documentação do endpoint.
- O proprietário do recurso especificado para o token corresponda ao proprietário do recurso que será afetado pelo ponto de extremidade. Para saber mais, confira Gerenciar seus tokens de acesso pessoal.
- O token tenha acesso aos repositórios privados que o ponto de extremidade afetará. Para saber mais, confira Gerenciar seus tokens de acesso pessoal.
- O proprietário do token tem as permissões necessárias para usar o endpoint. Por exemplo, se um ponto de extremidade só puder ser usado por proprietários da organização, apenas os usuários que forem proprietários da organização afetada poderão usá-lo.
- O token não tenha expirado ou não tenha sido revogado. Para saber mais, confira Vencimento e revogação de token.
Se estiver usando um token de acesso de instalação GitHub App, verifique que:
- O GitHub App tem as permissões necessárias para usar o endpoint. Para obter mais informações sobre as permissões necessárias, confira a documentação para o endpoint.
- O ponto de extremidade esteja afetando apenas os recursos pertencentes à conta em que o GitHub App estiver instalado.
- O GitHub App tem acesso a qualquer repositório que o endpoint afetará.
- O token não tenha expirado ou não tenha sido revogado. Para saber mais, confira Vencimento e revogação de token.
Se estiver usando um token de acesso de usuário do GitHub App, verifique que:
- O GitHub App tem as permissões necessárias para usar o endpoint. Para obter mais informações sobre as permissões necessárias, confira a documentação para o endpoint.
- O usuário que autorizou o token tem qualquer permissão necessária para usar o endpoint. Por exemplo, se um ponto de extremidade só puder ser usado por proprietários da organização, apenas os usuários que forem proprietários da organização afetada poderão usá-lo.
- O GitHub App tem acesso a qualquer repositório que o endpoint afetará.
- O usuário tem acesso a quaisquer repositórios que o endpoint afetará.
- O usuário aprovou todas as permissões atualizadas para seu GitHub App. Para saber mais, confira Aprovação de permissões atualizadas para um aplicativo GitHub.
Se estiver usando um token de acesso de usuário do OAuth app, verifique que:
- O token tenha os escopos necessários para usar o ponto de extremidade. Para saber mais, confira Escopos para aplicativos OAuth.
- O usuário que autorizou o token tem quaisquer permissões necessárias para usar o endpoint. Por exemplo, se um ponto de extremidade só puder ser usado por proprietários da organização, apenas os usuários que forem proprietários da organização afetada poderão usá-lo.
- A organização não bloqueou o acesso ao aplicativo OAuth, se estiver usando um endpoint que afetará os recursos pertencentes a uma organização. Os proprietários de aplicativos não possam ver se o aplicativo está bloqueado, mas podem instruir os usuários do aplicativo a verificar isso. Para obter mais informações, confira Sobre as restrições de acesso do aplicativo OAuth na documentação do GitHub Free.
- O token não tenha expirado ou não tenha sido revogado. Para saber mais, confira Vencimento e revogação de token.
Se estiver usando GITHUB_TOKEN em um fluxo de trabalho GitHub Actions, verifique que:
- O endpoint está afetando apenas os recursos pertencentes ao repositório onde o fluxo de trabalho está em execução. Caso precise acessar recursos fora desse repositório, como recursos de propriedade de uma organização ou recursos de propriedade de outro repositório, use um personal access token ou um token de acesso para um GitHub App.

Para obter mais informações sobre autenticação, confira Autenticação na API REST.

Você também deve verificar se há erros de digitação na sua URL. Por exemplo, adicionar uma barra final ao endpoint resultará em um 404 Not Found. Você pode consultar a documentação de referência do endpoint para confirmar que a URL está correta.

Além disso, todos os parâmetros de caminho devem ser codificados por URL. Por exemplo, todas as barras no valor do parâmetro devem ser substituídas por %2F. Se você não codificar corretamente nenhuma barra no nome do parâmetro, a URL do ponto de extremidade será interpretada incorretamente.

Resultados faltando

A maioria dos endpoints que retornam uma lista de recursos suporta paginação. Na maioria desses pontos de extremidade, apenas os primeiros 30 recursos são retornados por padrão. Para ver todos os recursos, é necessário paginar os resultados. Para saber mais, confira Como usar paginação na API REST.

Se estiver usando a paginação corretamente e ainda não forem exibidos todos os resultados esperados, confirme se as credenciais de autenticação usadas têm acesso a todos os recursos esperados. Por exemplo, se estiver usando um token de acesso de instalação do GitHub App, se a instalação tiver acesso permitido apenas a um subconjunto de repositórios em uma organização, a solicitação feita para todos os repositórios nessa organização retornará apenas os repositórios que o instalador do aplicativo pode acessar.

Tempo de espera

Se o GitHub demorar mais de 10 segundos para processar uma solicitação de API, o GitHub encerrará a solicitação e você receberá uma resposta de tempo limite e uma mensagem de "Erro do servidor".

O GitHub tem 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 REST 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 estiver solicitando 100 itens em uma página, poderá tentar solicitar menos itens.

Recurso não acessível

Se você estiver usando um GitHub App ou fine-grained personal access token e receber um erro “Recurso não acessível por integração” ou “Recurso não acessível por personal access token”, significa que seu token tem permissões insuficientes. Para obter mais informações sobre as permissões necessárias, confira a documentação para o endpoint.

Você pode usar o cabeçalho X-Accepted-GitHub-Permissions para identificar as permissões necessárias para acessar o ponto de extremidade da API REST.

O valor do cabeçalho X-Accepted-GitHub-Permissions é uma lista de permissões, separada por vírgulas, que são necessárias para usar o endpoint. Ocasionalmente, você pode escolher entre vários conjuntos de permissões. Nesses casos, várias listas separadas por vírgulas serão separadas por ponto-e-vírgula.

Por exemplo:

          `X-Accepted-GitHub-Permissions: contents=read` indica que o GitHub App ou fine-grained personal access token precisa de permissão de leitura do conteúdo.

          `X-Accepted-GitHub-Permissions: pull_requests=write,contents=read` indica que o GitHub App ou fine-grained personal access token precisa de acesso de gravação para a permissão de solicitação de pull e acesso de leitura para a permissão de conteúdo.

          `X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read` indica que o GitHub App ou fine-grained personal access token precisa de acesso de leitura para a permissão de solicitação de pull e acesso de leitura para a permissão de conteúdo ou acesso de leitura para a permissão de problemas e acesso de leitura para a permissão de conteúdo.

Problemas ao analisar o JSON

Se você enviar um JSON inválido no corpo da solicitação, receberá uma resposta 400 Bad Request e uma mensagem de erro de "Problemas ao analisar JSON". É possível usar um linter ou um validador JSON para ajudar a identificar erros em seu JSON.

O corpo deve ser um objeto JSON

Se o ponto de extremidade espera um objeto JSON e o corpo da solicitação não estiver formatado como um objeto JSON, você pode receber uma resposta 400 Bad Request e uma mensagem de erro "O corpo deve ser um objeto JSON".

Solicitação inválida

Se você omitir parâmetros necessários ou especificar o tipo errado de parâmetro, receberá uma resposta 422 Unprocessable Entity e uma mensagem de erro de "Solicitação inválida". Por exemplo, esse erro será exibido se você especificar determinado valor de parâmetro como matriz, mas o ponto de extremidade estiver esperando uma cadeia de caracteres. Consulte a documentação de referência do ponto de extremidade para verificar se está usando os tipos de parâmetros corretos e se está incluindo todos os parâmetros necessários.

Falha na Validação

Se sua solicitação não pôde ser processada, você pode receber uma resposta 422 Unprocessable Entity e uma mensagem de erro de "Falha na validação". O corpo da resposta incluirá uma propriedade errors, que contém uma propriedade code para ajudá-lo a diagnosticar o problema.

Code	Descrição
`missing`	O recurso não existe.
`missing_field`	Um parâmetro necessário não foi especificado. Revise a documentação do endpoint para ver quais são os parâmetros necessários.
`invalid`	A formatação de um parâmetro é inválida. Consulte a documentação do endpoint para obter informações mais específicas.
`already_exists`	Outro recurso tem o mesmo valor que um dos seus parâmetros. Isso pode acontecer em recursos que precisam ter alguma chave única (como nomes de etiqueta).
`unprocessable`	Os parâmetros fornecidos eram inválidos.
`custom`	Consulte a propriedade `message` para diagnosticar o erro.

Versão sem suporte

Você deve usar o cabeçalho X-GitHub-Api-Version para especificar uma versão da API. Por exemplo:

curl --header "X-GitHub-Api-Version:2022-11-28" https://api.github.com/zen

Se você especificar uma versão que não existe, receberá um erro 400 Bad Request e uma mensagem sobre ausência de suporte a essa versão.

Para saber mais, confira Versões da API.

        [AUTOTITLE](/rest/guides/best-practices-for-using-the-rest-api)

        [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/troubleshooting-webhooks)

        [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)

Neste artigo