Problembehandlung der REST-API

Ratenbegrenzungsfehler

GitHub erzwingt Ratenbegrenzungen, um sicherzustellen, dass die API für alle Benutzer verfügbar bleibt. Weitere Informationen finden Sie unter Ratenbegrenzungen für die REST-API.

Wenn Sie Ihre primäre Ratenbegrenzung überschreiten, erhalten Sie eine 403 Forbidden- oder 429 Too Many Requests -Antwort, und der x-ratelimit-remaining-Header lautet 0. Wenn Sie eine sekundäre Ratenbegrenzung überschreiten, erhalten Sie eine 403 Forbidden- oder 429 Too Many Requests -Antwort und eine Fehlermeldung, die angibt, dass Sie eine sekundäre Ratenbegrenzung überschritten haben.

Wenn Sie einen Ratenbegrenzungsfehler erhalten, sollten Sie gemäß den folgenden Richtlinien das Erstellen von Anforderungen vorübergehend beenden:

Wenn der Antwortheader retry-after vorhanden ist, sollten Sie Ihre Anforderung erst nach Ablauf dieser Sekundenzahl erneut übermitteln.
Wenn der x-ratelimit-remaining-Header 0 lautet, sollten Sie Anforderung erst nach Ablauf der im x-ratelimit-reset-Header angegebenen Zeit erneut senden. Der x-ratelimit-reset-Header ist in UTC-Epochensekunden angegeben.
Warten Sie andernfalls mindestens eine Minute, bevor Sie den Vorgang wiederholen. Wenn Ihre Anforderung aufgrund einer sekundären Ratenbegrenzung weiterhin fehlschlägt, warten Sie auf eine exponentiell steigende Zeitspanne zwischen Wiederholungen, und lösen Sie nach einer bestimmten Anzahl von Wiederholungen einen Fehler aus.

Wenn Sie weiterhin Anfragen stellen, während die Ratenbegrenzung eingeschränkt ist, kann dies zu einer Sperrung Ihrer Integration führen.

Weitere Informationen zum Vermeiden einer Überschreitung der Ratenbegrenzung findest du unter Bewährte Methoden für die Verwendung der REST-API.

`404 Not Found` einer vorhandenen Ressource

Wenn Sie eine Anforderung für den Zugriff auf eine private Ressource stellen und Ihre Anforderung nicht ordnungsgemäß authentifiziert ist, erhalten Sie eine 404 Not Found-Antwort. GitHub verwendet eine 404 Not Found-Antwort anstelle einer 403 Forbidden-Antwort, um zu vermeiden, dass private Repositorys vorhanden sind.

Wenn Sie eine 404 Not Found-Antwort erhalten, wenn Sie wissen, dass die angeforderte Ressource vorhanden ist, sollten Sie Ihre Authentifizierung überprüfen. Zum Beispiel:

Wenn Sie eine personal access token (classic) verwenden, sollten Sie Folgendes sicherstellen:
- Das Token verfügt über die Bereiche, die für die Verwendung des Endpunkts erforderlich sind. Weitere Informationen findest du unter Bereiche für OAuth-Apps und Verwalten deiner persönlichen Zugriffstoken.
- Der Besitzer/die Besitzerin des Tokens verfügt über alle Berechtigungen, die für die Verwendung des Endpunkts erforderlich sind. Wenn beispielsweise ein Endpunkt nur von Organisationseigentümer*innen verwendet werden kann, können nur Benutzer, die Besitzer der betroffenen Organisation sind, den Endpunkt verwenden.
- Das Token ist nicht abgelaufen oder wurde nicht widerrufen. Weitere Informationen finden Sie unter Tokenablauf und Sperrung.
Wenn Sie eine fine-grained personal access token verwenden, sollten Sie Folgendes sicherstellen:
- Das Token verfügt über die Berechtigungen, die für die Verwendung des Endpunkts erforderlich sind. Weitere Informationen zu den erforderlichen Berechtigungen sind in der Dokumentation für den Endpunkt zu finden.
- Der für das Token angegebene Ressourcenbesitzer stimmt mit dem Besitzer/der Besitzerin der Ressource überein, die sich auf den Endpunkt auswirkt. Weitere Informationen finden Sie unter Verwalten deiner persönlichen Zugriffstoken.
- Das Token hat Zugriff auf alle privaten Repositorys, die sich auf den Endpunkt auswirken. Weitere Informationen finden Sie unter Verwalten deiner persönlichen Zugriffstoken.
- Der Besitzer/die Besitzerin des Tokens verfügt über alle Berechtigungen, die für die Verwendung des Endpunkts erforderlich sind. Wenn beispielsweise ein Endpunkt nur von Organisationseigentümer*innen verwendet werden kann, können nur Benutzer, die Besitzer der betroffenen Organisation sind, den Endpunkt verwenden.
- Das Token ist nicht abgelaufen oder wurde nicht widerrufen. Weitere Informationen finden Sie unter Tokenablauf und Sperrung.
Wenn Sie ein GitHub App-Installationszugriffstoken verwenden, sollten Sie Folgendes sicherstellen:
- Die GitHub App verfügt über die Berechtigungen, die für die Verwendung des Endpunkts erforderlich sind. Weitere Informationen zu den erforderlichen Berechtigungen sind in der Dokumentation für den Endpunkt zu finden.
- Der Endpunkt wirkt sich nur auf Ressourcen aus, die im Besitz des Kontos sind, in dem die GitHub App installiert sind.
- Die GitHub App hat Zugriff auf alle Repositorys, die sich auf den Endpunkt auswirken.
- Das Token ist nicht abgelaufen oder wurde nicht widerrufen. Weitere Informationen finden Sie unter Tokenablauf und Sperrung.
Wenn Sie ein GitHub App-Benutzerzugriffstoken verwenden, sollten Sie Folgendes sicherstellen:
- Die GitHub App verfügt über die Berechtigungen, die für die Verwendung des Endpunkts erforderlich sind. Weitere Informationen zu den erforderlichen Berechtigungen sind in der Dokumentation für den Endpunkt zu finden.
- Der Benutzer, der das Token autorisiert hat, verfügt über alle Berechtigungen, die für die Verwendung des Endpunkts erforderlich sind. Wenn beispielsweise ein Endpunkt nur von Organisationsbesitzern verwendet werden kann, können nur Benutzer, die Besitzer der betroffenen Organisation sind, den Endpunkt verwenden.
- Die GitHub App hat Zugriff auf alle Repositorys, die sich auf den Endpunkt auswirken.
- Der Benutzer hat Zugriff auf alle Repositorys, die sich auf den Endpunkt auswirken.
- Der Benutzer hat alle aktualisierten Berechtigungen für Ihre GitHub App genehmigt. Weitere Informationen finden Sie unter Genehmigen aktualisierter Berechtigungen für eine GitHub-App.
Wenn Sie ein OAuth app-Benutzerzugriffstoken verwenden, sollten Sie Folgendes sicherstellen:
- Das Token verfügt über die Bereiche, die für die Verwendung des Endpunkts erforderlich sind. Weitere Informationen finden Sie unter Bereiche für OAuth-Apps.
- Der Benutzer, der das Token autorisiert hat, verfügt über alle Berechtigungen, die für die Verwendung des Endpunkts erforderlich sind. Wenn beispielsweise ein Endpunkt nur von Organisationsbesitzern verwendet werden kann, können nur Benutzer, die Besitzer der betroffenen Organisation sind, den Endpunkt verwenden.
- Die Organisation hat den OAuth-App-Zugriff nicht blockiert, wenn Sie einen Endpunkt verwenden, der sich auf Ressourcen im Besitz einer Organisation auswirkt. App-Besitzer können nicht sehen, ob ihre App blockiert ist, aber sie können Benutzer der App anweisen, dies zu überprüfen. Weitere Informationen findest du unter Informationen zu OAuth App-Zugriffseinschränkungen in der GitHub Free-Dokumentation.
- Das Token ist nicht abgelaufen oder wurde nicht widerrufen. Weitere Informationen finden Sie unter Tokenablauf und Sperrung.
Wenn Sie GITHUB_TOKEN in einem GitHub Actions-Workflow verwenden, sollten Sie Folgendes sicherstellen:
- Der Endpunkt wirkt sich nur auf Ressourcen aus, die im Besitz des Repositorys sind, in dem der Workflow ausgeführt wird. Wenn Sie auf Ressourcen außerhalb dieses Repositorys zugreifen müssen, z. B. Ressourcen, die sich im Besitz einer Organisation befinden, oder Ressourcen, die einem anderen Repository gehören, sollten Sie ein personal access token oder ein Zugriffstoken für eine GitHub App verwenden.

Weitere Informationen zur Authentifizierung findest du unter Authentifizieren bei der REST-API.

Sie sollten auch nach Tippfehlern in Ihrer URL suchen. Beispielsweise führt das Hinzufügen eines nachgestellten Schrägstrichs zum Endpunkt zu einem 404 Not Found. Sie können auf die Referenzdokumentation für den Endpunkt verweisen, um zu bestätigen, dass Sie über die richtige URL verfügen.

Darüber hinaus müssen alle Pfadparameter URL-codiert sein. Beispielsweise müssen alle Schrägstriche im Parameterwert durch %2F ersetzt werden. Wenn Sie Schrägstriche im Parameternamen nicht ordnungsgemäß codieren, wird die Endpunkt-URL falsch interpretiert.

Fehlende Ergebnisse

Die meisten Endpunkte, die eine Liste der Ressourcen zurückgeben, unterstützen die Paginierung. Für die meisten dieser Endpunkte werden standardmäßig nur die ersten 30 Ressourcen zurückgegeben. Um alle Ressourcen anzuzeigen, müssen Sie die Ergebnisse auslagern. Weitere Informationen finden Sie unter Verwenden der Paginierung in der REST-API.

Wenn Sie die Paginierung richtig verwenden und dennoch nicht alle erwarteten Ergebnisse sehen, sollten Sie bestätigen, dass die von Ihnen verwendeten Authentifizierungsanmeldeinformationen Zugriff auf alle erwarteten Ressourcen haben. Wenn Sie z. B. ein GitHub App-Installationszugriffstoken verwenden, wenn der Installation nur Zugriff auf eine Teilmenge von Repositorys in einer Organisation gewährt wurde, gibt jede Anforderung für alle Repositorys in dieser Organisation nur die Repositorys zurück, auf die die App-Installation zugreifen kann.

Timeouts

Wenn die Verarbeitung einer API-Anforderung durch GitHub Enterprise Server länger als zehn Sekunden dauert, wird die Anforderung durch GitHub Enterprise Server beendet, und Sie erhalten eine Serverfehlermeldung.

GitHub Enterprise Server behält sich das Recht vor, das Timeoutfenster zu ändern, um die Geschwindigkeit und Zuverlässigkeit der API zu schützen.

Sie können den Status der REST-API bei githubstatus.com überprüfen, um zu ermitteln, ob das Timeout auf ein Problem mit der API zurückzuführen ist. Sie können auch versuchen, Ihre Anfrage zu vereinfachen oder ihre Anfrage später zu testen. Wenn Sie beispielsweise 100 Elemente auf einer Seite anfordern, können Sie versuchen, weniger Elemente anzufordern.

Ressource nicht zugänglich

Wenn Sie eine GitHub App oder fine-grained personal access token verwenden und den Fehler erhalten, dass von der Integration nicht auf die Ressource zugegriffen werden kann oder dass von personal access token nicht auf die Ressource zugegriffen werden kann, weist Ihr Token unzureichende Berechtigungen auf. Weitere Informationen zu den erforderlichen Berechtigungen sind in der Dokumentation für den Endpunkt zu finden.

Sie können den X-Accepted-GitHub-Permissions-Header verwenden, um die Berechtigungen zu identifizieren, die für den Zugriff auf den REST-API-Endpunkt erforderlich sind.

Der Wert des X-Accepted-GitHub-Permissions-Headers ist eine durch Trennzeichen getrennte Liste der Berechtigungen, die für die Verwendung des Endpunkts erforderlich sind. Gelegentlich können Sie aus mehreren Berechtigungssätzen auswählen. In diesen Fällen werden mehrere durch Kommas getrennte Listen durch ein Semikolon getrennt.

Zum Beispiel:

X-Accepted-GitHub-Permissions: contents=read bedeutet, dass Ihre GitHub App oder fine-grained personal access token Lesezugriff auf die Inhaltsberechtigung benötigt.
X-Accepted-GitHub-Permissions: pull_requests=write,contents=read bedeutet, dass Ihr GitHub App oder fine-grained personal access token Schreibzugriff auf die Pullanforderungsberechtigung und Lesezugriff auf die Inhaltsberechtigung benötigt.
X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read bedeutet, dass Ihr GitHub App oder fine-grained personal access token entweder Lesezugriff auf die Berechtigung für die Pullanforderung und Lesezugriff auf die Berechtigung für die Inhalte oder Lesezugriff auf die Berechtigung für Probleme und Lesezugriff auf die Inhaltsberechtigung benötigt.

Probleme beim Analysieren von JSON

Wenn Sie im Anforderungstext ungültige JSON senden, erhalten Sie möglicherweise eine 400 Bad Request-Antwort und die Fehlermeldung, dass Probleme beim Analysieren von JSON auftreten. Sie können einen Linter- oder JSON-Validator verwenden, um Fehler in Ihrem JSON-Code zu identifizieren.

Der Text sollte ein JSON-Objekt sein.

Wenn der Endpunkt ein JSON-Objekt erwartet und Sie Ihren Anforderungstext nicht als JSON-Objekt formatieren, erhalten Sie möglicherweise eine 400 Bad Request-Antwort und die Fehlermeldung, dass der Text ein JSON-Objekt sein sollte.

Ungültige Anforderung

Wenn Sie die erforderlichen Parameter weglassen oder den falschen Typ für einen Parameter verwenden, erhalten Sie möglicherweise eine 422 Unprocessable Entity-Antwort und die Fehlermeldung „Ungültige Anforderung“. Beispielsweise erhalten Sie diesen Fehler, wenn Sie einen Parameterwert als Array angeben, der Endpunkt jedoch eine Zeichenfolge erwartet. Sie können auf die Referenzdokumentation für den Endpunkt verweisen, um zu überprüfen, ob Sie die richtigen Parametertypen verwenden, und dass Sie alle erforderlichen Parameter einschließen.

Überprüfung fehlgeschlagen

Wenn Ihre Anforderung nicht verarbeitet werden konnte, erhalten Sie möglicherweise eine 422 Unprocessable Entity-Antwort und die Fehlermeldung, dass bei der Überprüfung ein Fehler aufgetreten ist. Der Antworttext enthält eine errors-Eigenschaft, die eine code-Eigenschaft enthält, mit der Sie das Problem diagnostizieren können.

Code	Beschreibung
`missing`	Eine Ressource ist nicht vorhanden.
`missing_field`	Ein erforderlicher Parameter wurde nicht angegeben. Überprüfen Sie die Dokumentation für den Endpunkt, um zu sehen, welche Parameter erforderlich sind.
`invalid`	Die Formatierung eines Felds ist ungültig. Weitere spezifische Informationen finden Sie in der Dokumentation.
`already_exists`	Eine andere Ressource weist den gleichen Wert wie einer Ihrer Parameter auf. Dies kann bei Ressourcen der Fall sein, die einen eindeutigen Schlüssel haben müssen (z. B. Bezeichnungsnamen).
`unprocessable`	Die bereitgestellten Parameter waren ungültig.
`custom`	Verweisen Sie auf die `message`-Eigenschaft, um den Fehler zu diagnostizieren.

Kine unterstützte SDK-Version

Sie sollten den X-GitHub-Api-Version-Header verwenden, um eine API-Version anzugeben. Zum Beispiel:

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

Wenn Sie eine nicht vorhandene Version angeben, wird eine 400 Bad Request-Fehlermeldung angezeigt, und es wird eine Meldung angezeigt, dass die Version nicht unterstützt wird.

Weitere Informationen finden Sie unter API-Versionen.

Benutzer-Agent erforderlich

Anforderungen ohne gültigen User-Agent-Header werden abgelehnt. Sie sollten Ihren Benutzernamen oder den Namen Ihrer Anwendung für den User-Agent-Wert verwenden.

curl sendet standardmäßig einen gültigen User-Agent-Header.

Sonstige Fehler

Wenn Sie einen Fehler beobachten, der hier nicht besprochen wird, sollten Sie sich auf die Fehlermeldung beziehen, die Sie von der API erhalten. Die meisten Fehlermeldungen geben einen Hinweis darauf, was falsch ist, und einen Link zu relevanten Dokumentationen.

Wenn Sie unerwartete Fehler beobachten, können Sie githubstatus.com oder die GitHub-Status-API verwenden, um nach Vorfällen zu suchen, die sich auf die API auswirken.