Résolution des problèmes de l’API REST

Erreurs de limite de débit

GitHub applique les limites de débit pour s’assurer que l’API reste disponible pour tous les utilisateurs. Pour plus d’informations, consultez « Limites de débit pour l'API REST ».

Si vous dépassez votre limite de débit primaire, vous recevrez une réponse 403 Forbidden ou 429 Too Many Requests et l’en-tête x-ratelimit-remaining sera 0. Si vous dépassez une limite de débit secondaire, vous recevrez une réponse 403 Forbidden ou 429 Too Many Requests et un message d’erreur indiquant que vous avez dépassé une limite de débit secondaire.

Si vous recevez une erreur de limite de débit, vous devez arrêter temporairement d’effectuer des demandes en fonction des instructions suivantes :

Si l'en-tête de réponse retry-after est présent, vous ne devez pas réessayer votre demande avant le nombre de secondes spécifié.
Si l’en-tête x-ratelimit-remaining est 0, vous ne devez pas effectuer une autre demande avant la durée spécifiée par l’en-tête x-ratelimit-reset. L’en-tête x-ratelimit-reset est en secondes d’époque UTC.
Sinon, attendez au moins une minute avant de réessayer. Si votre demande continue d'échouer en raison d'une limite de débit secondaire, attendez une durée exponentiellement croissante entre les nouvelles tentatives et levez une erreur après un nombre spécifique de nouvelles tentatives.

La poursuite des demandes pendant que vous êtes limité peut entraîner l'interdiction de votre intégration.

Pour plus d’informations sur la façon d’éviter de dépasser les limites de débit, consultez Meilleures pratiques pour utiliser l'API REST.

`404 Not Found` pour une ressource existante

Si vous effectuez une demande d’accès à une ressource privée et que votre demande n’est pas correctement authentifiée, vous recevrez une réponse 404 Not Found. GitHub utilise une réponse 404 Not Found au lieu d’une réponse 403 Forbidden pour éviter de confirmer l’existence de référentiels privés.

Si vous recevez une réponse 404 Not Found lorsque vous savez que la ressource que vous demandez existe, vous devez case activée votre authentification. Par exemple :

Si vous utilisez un personal access token (classic), vous devez vous assurer que :
- Le jeton a les étendues requises pour utiliser le point de terminaison. Pour plus d’informations, consultez « Étendues des applications OAuth » et « Gestion de vos jetons d'accès personnels ».
- Le propriétaire du jeton dispose des autorisations nécessaires pour utiliser le point de terminaison. Par exemple, si un point de terminaison ne peut être utilisé que par des propriétaire d'organisation s, seuls les utilisateurs propriétaires de l’organisation concernée peuvent utiliser le point de terminaison.
- Le jeton n’a pas expiré ou n’a pas été révoqué. Pour plus d’informations, consultez « Expiration et révocation des jetons ».
Si vous utilisez un fine-grained personal access token, vous devez vous assurer que :
- Le jeton dispose des autorisations nécessaires pour utiliser le point de terminaison. Consultez la documentation du point de terminaison pour obtenir plus d’informations sur les autorisations requises.
- Le propriétaire de la ressource spécifié pour le jeton correspond au propriétaire de la ressource affectée par le point de terminaison. Pour plus d’informations, consultez « Gestion de vos jetons d'accès personnels ».
- Le jeton a accès à tous les référentiels privés affectés par le point de terminaison. Pour plus d’informations, consultez « Gestion de vos jetons d'accès personnels ».
- Le propriétaire du jeton dispose des autorisations nécessaires pour utiliser le point de terminaison. Par exemple, si un point de terminaison ne peut être utilisé que par des propriétaire d'organisation s, seuls les utilisateurs propriétaires de l’organisation concernée peuvent utiliser le point de terminaison.
- Le jeton n’a pas expiré ou n’a pas été révoqué. Pour plus d’informations, consultez « Expiration et révocation des jetons ».
Si vous utilisez un jeton d’accès d’installation GitHub App, vérifiez que :
- Les GitHub App disposent des autorisations requises pour utiliser le point de terminaison. Consultez la documentation du point de terminaison pour obtenir plus d’informations sur les autorisations requises.
- Le point de terminaison affecte uniquement les ressources appartenant au compte où les GitHub App sont installées.
- Les GitHub App ont accès aux référentiels affectés par le point de terminaison.
- Le jeton n’a pas expiré ou n’a pas été révoqué. Pour plus d’informations, consultez « Expiration et révocation des jetons ».
Si vous utilisez un jeton d’accès utilisateur GitHub App, vérifiez que :
- Les GitHub App disposent des autorisations requises pour utiliser le point de terminaison. Consultez la documentation du point de terminaison pour obtenir plus d’informations sur les autorisations requises.
- L’utilisateur qui a autorisé le jeton dispose d’autorisations requises pour utiliser le point de terminaison. Par exemple, si un point de terminaison ne peut être utilisé que par des propriétaire d'organisation s, seuls les utilisateurs propriétaires de l’organisation concernée peuvent utiliser le point de terminaison.
- Les GitHub App ont accès aux référentiels affectés par le point de terminaison.
- L’utilisateur a accès à tous les référentiels affectés par le point de terminaison.
- L’utilisateur a approuvé toutes les autorisations mises à jour pour vos GitHub App. Pour plus d’informations, consultez « Approbation des autorisations mises à jour pour une application GitHub ».
Si vous utilisez un jeton d’accès utilisateur OAuth app, vérifiez que :
- Le jeton a les étendues requises pour utiliser le point de terminaison. Pour plus d’informations, consultez « Étendues des applications OAuth ».
- L’utilisateur qui a autorisé le jeton dispose d’autorisations requises pour utiliser le point de terminaison. Par exemple, si un point de terminaison ne peut être utilisé que par des propriétaire d'organisation s, seuls les utilisateurs propriétaires de l’organisation concernée peuvent utiliser le point de terminaison.
- L’organisation n’a pas bloqué l’accès aux applications OAuth, si vous utilisez un point de terminaison qui affectera les ressources appartenant à une organisation. Les propriétaires d’applications ne peuvent pas voir si leur application est bloquée, mais ils peuvent demander aux utilisateurs de l’application de case activée cela. Pour plus d’informations, consultez À propos des restrictions d’accès des applications OAuth.
- Le jeton n’a pas expiré ou n’a pas été révoqué. Pour plus d’informations, consultez « Expiration et révocation des jetons ».
Si vous utilisez GITHUB_TOKEN dans un flux de travail GitHub Actions, vérifiez que :
- Le point de terminaison affecte uniquement les ressources détenues par le référentiel où le flux de travail est en cours d’exécution. Si vous devez accéder aux ressources en dehors de ce référentiel, telles que les ressources appartenant à une organisation ou des ressources appartenant à un autre référentiel, vous devez utiliser un personal access token ou un jeton d’accès pour un GitHub App.

Pour plus d’informations sur l’authentification, consultez Authentification auprès de l’API REST.

Vous devez également case activée pour les fautes de frappe dans votre URL. Par exemple, l’ajout d’une barre oblique de fin au point de terminaison entraîne un 404 Not Found. Vous pouvez consulter la documentation de référence du point de terminaison pour confirmer que vous disposez de l’URL correcte.

En outre, tous les paramètres de chemin d’accès doivent être encodés dans l’URL. Par exemple, toutes les barres obliques de la valeur du paramètre doivent être remplacées par %2F. Si vous n’encodez pas correctement les barres obliques dans le nom du paramètre, l’URL du point de terminaison ne sera pas interprétée correctement.

Résultats manquants

La plupart des points de terminaison qui retournent une liste de ressources prennent en charge la pagination. Pour la plupart de ces points de terminaison, seules les 30 premières ressources sont retournées par défaut. Pour afficher toutes les ressources, vous devez paginer les résultats. Pour plus d’informations, consultez « Utilisation de la pagination dans l’API REST ».

Si vous utilisez correctement la pagination et que vous ne voyez toujours pas tous les résultats attendus, vérifiez que les informations d’identification d’authentification que vous avez utilisées ont accès à toutes les ressources attendues. Par exemple, si vous utilisez un jeton d’accès d’installation GitHub App, si l’installation n’a été accordée qu’à un sous-ensemble de référentiels d’une organisation, toute demande de tous les référentiels de cette organisation retourne uniquement les référentiels auxquels l’installation de l’application peut accéder.

Nécessite une authentification lors de l’utilisation de l’authentification de base

L’authentification de base avec votre nom d’utilisateur et votre mot de passe n’est pas prise en charge. À la place, vous devez utiliser une personal access token or un jeton d’accès pour un GitHub App ou OAuth app. Pour plus d’informations, consultez « Authentification auprès de l’API REST ».

Délais d'attente

Si GitHub prend plus de 10 secondes pour traiter une demande d’API, GitHub mettra fin à la demande et vous recevrez une réponse de délai expiré et un message d’« Erreur de serveur ».

GitHub se réserve le droit de modifier le délai d’expiration pour protéger la vitesse et la fiabilité de l’API.

Vous pouvez case activée l’état de l’API REST à githubstatus.com pour déterminer si le délai d’expiration est dû à un problème avec l’API. Vous pouvez également essayer de simplifier votre demande ou d’essayer votre demande ultérieurement. Par exemple, si vous demandez 100 articles sur une page, vous pouvez essayer de demander moins d’articles.

Ressource non accessible

Si vous utilisez un GitHub App ou fine-grained personal access token et que vous recevez une erreur « Ressource non accessible par intégration » ou « Ressource non accessible par personal access token », votre jeton a des autorisations insuffisantes. Consultez la documentation du point de terminaison pour obtenir plus d’informations sur les autorisations requises.

Vous pouvez utiliser l’en-tête X-Accepted-GitHub-Permissions pour identifier les autorisations requises pour accéder au point de terminaison de l’API REST.

La valeur de l’en-tête X-Accepted-GitHub-Permissions est une liste séparée par des virgules des autorisations requises pour utiliser le point de terminaison. Parfois, vous pouvez choisir parmi plusieurs ensembles d’autorisations. Dans ce cas, les diverses listes séparées par des virgules seront séparées par un point-virgule.

Par exemple :

X-Accepted-GitHub-Permissions: contents=read signifie que votre GitHub App ou fine-grained personal access token a besoin d’un accès en lecture à l’autorisation de contenu.
X-Accepted-GitHub-Permissions: pull_requests=write,contents=read signifie que votre GitHub App ou fine-grained personal access token a besoin d’un accès en écriture à l’autorisation de demande de tirage (pull request) et d’accès en lecture à l’autorisation de contenu.
X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read signifie que votre GitHub App ou fine-grained personal access token a besoin soit d’un accès en lecture à l’autorisation de demande de tirage (pull request) et d’un accès en lecture à l’autorisation de contenu, ou alors d’un accès en lecture aux problèmes d’autorisation et d’un accès en lecture à l’autorisation de contenu.

Problèmes d’analyse JSON

Si vous envoyez un JSON non valide dans le corps de la demande, vous pouvez recevoir une réponse 400 Bad Request et un message d’erreur « Problèmes d’analyse JSON ». Vous pouvez utiliser un validateur linter ou JSON pour vous aider à identifier les erreurs dans votre JSON.

Le corps doit être un objet JSON

Si le point de terminaison attend un objet JSON et que vous ne mettez pas en forme votre corps de requête en tant qu’objet JSON, vous pouvez recevoir une réponse 400 Bad Request et un message d’erreur « Corps doit être un objet JSON ».

Demande non valide

Si vous omettez les paramètres requis ou que vous utilisez le type incorrect pour un paramètre, vous pouvez recevoir une réponse 422 Unprocessable Entity et un message d’erreur « Demande non valide ». Par exemple, vous obtiendrez cette erreur si vous spécifiez une valeur de paramètre en tant que tableau, mais que le point de terminaison attend une chaîne. Vous pouvez consulter la documentation de référence du point de terminaison pour vérifier que vous utilisez les types de paramètres corrects et que vous incluez tous les paramètres obligatoires.

Échec de la validation

Si votre demande n’a pas pu être traitée, vous pouvez recevoir une réponse 422 Unprocessable Entity et un message d’erreur « Échec de validation ». Le corps de la réponse inclut une propriété errors, qui inclut une propriété code pour vous aider à diagnostiquer le problème.

Code	Description
`missing`	Une ressource n’existe pas.
`missing_field`	Un paramètre requis n’a pas été spécifié. Passez en revue la documentation du point de terminaison pour voir quels paramètres sont requis.
`invalid`	La mise en forme d’un paramètre n’est pas valide. Pour plus d’informations, consultez la documentation du point de terminaison.
`already_exists`	Une autre ressource a la même valeur que l’un de vos paramètres. Cela peut se produire dans les ressources qui doivent disposer d’une clé unique (par exemple les noms d’étiquette).
`unprocessable`	Les paramètres fournis n’étaient pas valides.
`custom`	Reportez-vous à la propriété `message` pour diagnostiquer l’erreur.

Version non prise en charge

Vous devez utiliser l’en-tête X-GitHub-Api-Version pour spécifier une version d’API. Par exemple :

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

Si vous spécifiez une version qui n’existe pas, vous recevrez une erreur 400 Bad Requestet un message indiquant que la version n’est pas prise en charge.

Pour plus d’informations, consultez « Versions des API ».