Устранение неполадок с 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.
В противном случае дождитесь хотя бы одной минуты, прежде чем повторить попытку. Если запрос продолжает завершаться ошибкой из-за дополнительного ограничения скорости, подождите экспоненциально увеличивающееся время между повторными попытками и вызовите ошибку после определенного числа повторных попыток.

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

Дополнительные сведения о том, как избежать превышения ограничений скорости, см. в разделе Рекомендации по использованию 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 установлено устройство.
- Доступ GitHub App к любым репозиториям, влияющим на конечную точку.
- Срок действия маркера не истек или отменен. Дополнительные сведения см. в разделе Истечение срока действия и отзыв маркера.
Если вы используете GitHub App маркер доступа пользователя, убедитесь, что:
- У GitHub App него есть разрешения, необходимые для использования конечной точки. Дополнительные сведения о необходимых разрешениях см. в документации по конечной точке.
- Пользователь, авторизованный маркером, имеет все разрешения, необходимые для использования конечной точки. Например, если конечная точка может использоваться только владелец организации, пользователи, которые являются владельцами затронутой организации, могут использовать конечную точку.
- Доступ 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 AppOAuth app. Дополнительные сведения см. в разделе Проверка подлинности в REST API.

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

Если GitHub для обработки запроса API требуется более 10 секунд, 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 требуется доступ на запись к разрешению запроса на вытягивание и доступ на чтение к разрешению содержимого.
X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read означает, что GitHub App вам или fine-grained personal access token нужен доступ на чтение к разрешению запроса на вытягивание и доступ на чтение к разрешению содержимого, или доступ на чтение к разрешениям на чтение и доступ на чтение к разрешению на чтение.

Проблемы с анализом 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.