Устранение неполадок с REST API

Ошибки ограничения скорости

GitHub применяет ограничения скорости, чтобы обеспечить доступность API для всех пользователей. Дополнительные сведения см. в разделе Ограничения скорости для REST API.

Если вы превышаете основной предел скорости, вы получите 403 Forbidden или 429 Too Many Requests ответ, и x-ratelimit-remaining заголовок будет 0. При превышении дополнительного ограничения скорости вы получите 403 Forbidden или 429 Too Many Requests ответ и сообщение об ошибке, указывающее, что превышено дополнительное ограничение скорости.

Если вы получаете ошибку ограничения скорости, следует временно прекратить выполнение запросов в соответствии с этими рекомендациями:

        `retry-after` Если заголовок ответа присутствует, не следует повторять запрос до тех пор, пока не истекло много секунд.

Если заголовок x-ratelimit-remaining имеет значение 0, вы не должны выполнять другой запрос до тех пор, пока время, указанное заголовком x-ratelimit-reset . Заголовок x-ratelimit-reset находится в секундах эпохи UTC.
В противном случае дождитесь хотя бы одной минуты, прежде чем повторить попытку. Если запрос продолжает завершаться ошибкой из-за дополнительного ограничения скорости, подождите экспоненциально увеличивающееся время между повторными попытками и вызовите ошибку после определенного числа повторных попыток.

Продолжая делать запросы во время ограничения скорости, может привести к запрету интеграции.

Дополнительные сведения о просмотре действий API организации, включая превышение ограничений на основную ставку, см. в разделе Просмотр аналитики API в организации.

Дополнительные сведения о том, как избежать превышения ограничений скорости, см. в разделе Рекомендации по использованию REST API.

          `404 Not Found` для существующего ресурса

Если вы отправляете запрос на доступ к частному ресурсу и ваш запрос не проходит проверку подлинности, вы получите 404 Not Found ответ. GitHub использует 404 Not Found ответ вместо 403 Forbidden ответа, чтобы избежать подтверждения существования частных репозиториев.

Если вы получите 404 Not Found ответ, когда вы знаете, что ресурс, который вы запрашиваете, существует, необходимо проверить проверку подлинности. Например:

Если вы используете personal access token (classic), убедитесь, что:
- Маркер содержит области, необходимые для использования конечной точки. Дополнительные сведения см. в разделе [AUTOTITLE и Области для приложений OAuth](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).
- Владелец маркера имеет все разрешения, необходимые для использования конечной точки. Например, если конечная точка может использоваться только владелец организации, пользователи, которые являются владельцами затронутой организации, могут использовать конечную точку.
- Срок действия маркера не истек или отменен. Дополнительные сведения см. в разделе Истечение срока действия и отзыв маркера.
Если вы используете fine-grained personal access token, убедитесь, что:
- Маркер имеет разрешения, необходимые для использования конечной точки. Дополнительные сведения о необходимых разрешениях см. в документации по конечной точке.
- Владелец ресурса, указанный для маркера, соответствует владельцу ресурса, который будет влиять на конечную точку. Дополнительные сведения см. в разделе Управление личными маркерами доступа.
- Маркер имеет доступ к любым частным репозиториям, влияющим на конечную точку. Дополнительные сведения см. в разделе Управление личными маркерами доступа.
- Владелец маркера имеет все разрешения, необходимые для использования конечной точки. Например, если конечная точка может использоваться только владелец организации, пользователи, которые являются владельцами затронутой организации, могут использовать конечную точку.
- Срок действия маркера не истек или отменен. Дополнительные сведения см. в разделе Истечение срока действия и отзыв маркера.
Если вы используете маркер доступа к установке GitHub App , убедитесь, что:
- У GitHub App есть разрешения, необходимые для использования конечной точки. Дополнительные сведения о необходимых разрешениях см. в документации по конечной точке.
- Конечная точка влияет только на ресурсы, принадлежащие учетной записи, в которой установлен GitHub App.
- У variables.product.prodname_github_app %} есть доступ к любым репозиториям, влияющим на конечную точку.
- Срок действия маркера не истек или отменен. Дополнительные сведения см. в разделе Истечение срока действия и отзыв маркера.
Если вы используете маркер доступа пользователя GitHub App, убедитесь, что:
- У GitHub App есть разрешения, необходимые для использования конечной точки. Дополнительные сведения о необходимых разрешениях см. в документации по конечной точке.
- Пользователь, авторизованный маркером, имеет все разрешения, необходимые для использования конечной точки. Например, если конечная точка может использоваться только владелец организации, пользователи, которые являются владельцами затронутой организации, могут использовать конечную точку.
- У variables.product.prodname_github_app %} есть доступ к любым репозиториям, влияющим на конечную точку.
- Пользователь имеет доступ к любым репозиториям, влияющим на конечную точку.
- Пользователь одобрил все обновленные разрешения для ваших данных GitHub App. Дополнительные сведения см. в разделе Утверждение обновленных разрешений для приложения GitHub.
Если вы используете маркер доступа пользователя OAuth app, убедитесь, что:
- Маркер содержит области, необходимые для использования конечной точки. Дополнительные сведения см. в разделе Области для приложений OAuth.
- Пользователь, авторизованный маркером, имеет все разрешения, необходимые для использования конечной точки. Например, если конечная точка может использоваться только владелец организации, пользователи, которые являются владельцами затронутой организации, могут использовать конечную точку.
- Организация не блокирует доступ к приложению OAuth, если вы используете конечную точку, которая повлияет на ресурсы, принадлежащие организации. Владельцы приложений не могут узнать, заблокировано ли приложение, но они могут указать пользователям приложения проверить это. Дополнительные сведения см. в разделе Сведения об ограничениях доступа к приложению OAuth.
- Срок действия маркера не истек или отменен. Дополнительные сведения см. в разделе Истечение срока действия и отзыв маркера.
Если вы используете GITHUB_TOKEN в рабочем процессе GitHub Actions, убедитесь, что:
- Конечная точка влияет только на ресурсы, принадлежащие репозиторию, в котором выполняется рабочий процесс. Если вам нужно получить доступ к ресурсам за пределами этого репозитория, например к ресурсам, принадлежащим организации или ресурсам, принадлежащим другому репозиторию, следует использовать personal access token или маркер доступа для GitHub App.

Дополнительные сведения о проверке подлинности см. в разделе Проверка подлинности в REST API.

Вы также должны проверить типопечатки в URL-адресе. Например, добавление косой черты в конечную точку приведет к добавлению 404 Not Foundкосой черты. Вы можете обратиться к справочной документации для конечной точки, чтобы убедиться, что у вас есть правильный URL-адрес.

Кроме того, все параметры пути должны быть закодированы по URL-адресу. Например, все косые черты в значении параметра должны быть заменены %2Fна . Если вы неправильно закодируете косую черту в имени параметра, URL-адрес конечной точки будет неправильно интерпретирован.

Отсутствующие результаты

Большинство конечных точек, возвращающих список ресурсов, поддерживают разбиение на страницы. Для большинства этих конечных точек возвращаются только первые 30 ресурсов по умолчанию. Чтобы просмотреть все ресурсы, необходимо выполнить разбивку по результатам. Дополнительные сведения см. в разделе Использование разбиения на страницы в REST API.

Если вы используете разбивку на страницы правильно и по-прежнему не видите все ожидаемые результаты, убедитесь, что учетные данные проверки подлинности, используемые вами, имеют доступ ко всем ожидаемым ресурсам. Например, если вы используете маркер доступа к установке GitHub App, если установка была предоставлена только подмножеству репозиториев в организации, любой запрос на все репозитории в этой организации вернет только репозитории, к которым может получить доступ установка приложения.

Требуется проверка подлинности при использовании базовой проверки подлинности

Обычная проверка подлинности с помощью имени пользователя и пароля не поддерживается. Вместо этого следует использовать personal access token или маркер доступа для GitHub App или OAuth app. Дополнительные сведения см. в разделе Проверка подлинности в REST API.

Время ожидания

Если GitHub занимает более 10 секунд для обработки запроса API, GitHub завершит запрос, и вы получите ответ времени ожидания и сообщение об ошибке сервера.

GitHub резервирует право изменить окно времени ожидания для защиты скорости и надежности API.

Вы можете проверить состояние REST API в githubstatus.com , чтобы определить, связано ли время ожидания с проблемой с API. Вы также можете попытаться упростить запрос или попробовать его позже. Например, если вы запрашиваете 100 элементов на странице, попробуйте запросить меньше элементов.

Ресурс недоступен

Если вы используете GitHub App или fine-grained personal access token и получаете сообщение "Ресурс недоступен по интеграции" или "Ресурс недоступен personal access token", то у маркера недостаточно разрешений. Дополнительные сведения о необходимых разрешениях см. в документации по конечной точке.

Вы можете использовать заголовок X-Accepted-GitHub-Permissions для определения разрешений, необходимых для доступа к REST API endpoint.

Значение заголовка X-Accepted-GitHub-Permissions — это разделённый на запятую список разрешений, необходимых для использования конечной точки. Иногда можно выбрать несколько наборов разрешений. В этих случаях несколько разделенных запятыми списков будут разделены точкой с запятой.

Например:

        `X-Accepted-GitHub-Permissions: contents=read` означает, что ваш GitHub App или fine-grained personal access token нуждается в разрешении чтения содержимого.

        `X-Accepted-GitHub-Permissions: pull_requests=write,contents=read` означает, что ваш GitHub App или fine-grained personal access token нуждается в записи разрешения на pull request и доступ к разрешениям на чтение содержимого.

        `X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read` означает, что ваш GitHub App или fine-grained personal access token нуждается либо в доступе для чтения к разрешениям на pull request и к разрешениям на содержание, либо к разрешениям на чтение и к разрешению на чтение содержимого.

Проблемы с анализом JSON

Если вы отправляете недопустимый КОД JSON в тексте запроса, вы можете получить 400 Bad Request ответ и сообщение об ошибке "Проблемы синтаксического анализа JSON". Для выявления ошибок в JSON можно использовать проверяющий элемент linter или JSON.

Текст должен быть объектом JSON

Если конечная точка ожидает объект JSON и не форматирует текст запроса в виде объекта JSON, может появиться 400 Bad Request ответ и сообщение об ошибке "Текст должен быть объектом JSON".

Недопустимый запрос

Если вы опустите необходимые параметры или используете неправильный тип для параметра, вы можете получить 422 Unprocessable Entity ответ и сообщение об ошибке "Недопустимый запрос". Например, вы получите эту ошибку, если указать значение параметра в виде массива, но конечная точка ожидает строку. Вы можете обратиться к справочной документации для конечной точки, чтобы убедиться, что вы используете правильные типы параметров и включаете все необходимые параметры.

Проверка завершена с ошибкой.

Если запрос не удалось обработать, вы можете получить 422 Unprocessable Entity ответ и сообщение об ошибке "Сбой проверки". Текст ответа будет содержать errors свойство, которое включает code свойство, которое поможет вам диагностировать проблему.

Код	Описание
`missing`	Ресурс не существует.
`missing_field`	Обязательный параметр не указан. Ознакомьтесь с документацией по конечной точке, чтобы узнать, какие параметры необходимы.
`invalid`	Недопустимое форматирование параметра. Дополнительные сведения см. в документации по конечной точке.
`already_exists`	Другой ресурс имеет то же значение, что и один из параметров. Это может произойти с ресурсами, которые должны иметь уникальные ключи (например, имена меток).
`unprocessable`	Предоставленные параметры были недопустимыми.
`custom`	Чтобы диагностировать ошибку, `message` обратитесь к свойству.

Не поддерживается версия

Вам следует использовать заголовок X-GitHub-Api-Version для указания версии API. Например:

curl --header "X-GitHub-Api-Version:2026-03-10" https://api.github.com/zen

Если указать версию, которая не существует, появится 400 Bad Request сообщение об ошибке и сообщение о том, что версия не поддерживается.

Дополнительные сведения см. в разделе Версии 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)