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 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.

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` 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 tenha todas as permissões necessárias para usar o ponto de extremidade. 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 tenha as permissões necessárias para usar o ponto de extremidade. Para obter mais informações sobre as permissões necessárias, confira a documentação para o ponto de extremidade.
- 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 tenha todas as permissões necessárias para usar o ponto de extremidade. 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 tenha as permissões necessárias para usar o ponto de extremidade. Para obter mais informações sobre as permissões necessárias, confira a documentação para o ponto de extremidade.
- O ponto de extremidade esteja afetando apenas os recursos pertencentes à conta em que o GitHub App estiver instalado.
- O GitHub App tenha acesso aos repositórios que o ponto de extremidade 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 tenha as permissões necessárias para usar o ponto de extremidade. Para obter mais informações sobre as permissões necessárias, confira a documentação para o ponto de extremidade.
- O usuário que autorizou o token tenha todas as permissões necessárias para usar o ponto de extremidade. 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 tenha acesso aos repositórios que o ponto de extremidade afetará.
- O usuário tenha acesso a todos os repositórios que o ponto de extremidade afetará.
- O usuário tenha aprovado 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 tenha todas as permissões necessárias para usar o ponto de extremidade. 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 tenha bloquado o acesso ao aplicativo OAuth, se estiver usando um ponto de extremidade 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 ponto de extremidade esteja afetando apenas os recursos pertencentes ao repositório em que o fluxo de trabalho está sendo executado. 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, a adição de uma barra à direita ao ponto de extremidade resultará em um arquivo 404 Not Found. Você pode consultar a documentação de referência do ponto de extremidade 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 pontos de extremidade que retornam uma lista de recursos dão suporte à 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.

Tempos limite

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

GitHub Enterprise Server se reserva o direito de alterar o período de tempo limite para proteger a velocidade e 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 ponto de extremidade.

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 separada por vírgulas das permissões necessárias para usar o ponto de extremidade. 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 significa que o GitHub App ou fine-grained personal access token precisa de acesso de leitura à permissão de conteúdo.
X-Accepted-GitHub-Permissions: pull_requests=write,contents=read significa que o GitHub App ou fine-grained personal access token precisa de acesso para gravação à permissão de pull request e de acesso de leitura à permissão de conteúdo.
X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read significa que seu GitHub App ou fine-grained personal access token precisa de acesso de leitura à permissão de pull request e de acesso de leitura à permissão de conteúdo ou acesso de leitura à permissão de problemas e acesso de leitura à 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 validador do linter ou do JSON para ajudá-lo 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.

Código	Descrição
`missing`	Um recurso não existe.
`missing_field`	Um parâmetro necessário não foi especificado. Revise a documentação sobre ponto de extremidade para ver quais são os parâmetros necessários.
`invalid`	A formatação de um parâmetro é inválida. Revise a documentação sobre ponto de extremidade 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.

Neste artigo