This version of GitHub Enterprise Server was discontinued on 2024-01-04. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

Troubleshooting the REST API

In this article

Learn how to diagnose and resolve common problems for the REST API.

Rate limit errors

GitHub enforces rate limits to ensure that the API stays available for all users. For more information, see "Rate limits for the REST API."

If you exceed your primary rate limit, you will receive a 403 Forbidden or 429 Too Many Requests response, and the x-ratelimit-remaining header will be 0. If you exceed a secondary rate limit, you will receive a 403 Forbidden or 429 Too Many Requests response and an error message that indicates that you exceeded a secondary rate limit.

If you receive a rate limit error, you should stop making requests temporarily according to these guidelines:

  • If the retry-after response header is present, you should not retry your request until after that many seconds has elapsed.
  • If the x-ratelimit-remaining header is 0, you should not make another request until after the time specified by the x-ratelimit-reset header. The x-ratelimit-reset header is in UTC epoch seconds.
  • Otherwise, wait for at least one minute before retrying. If your request continues to fail due to a secondary rate limit, wait for an exponentially increasing amount of time between retries, and throw an error after a specific number of retries.

Continuing to make requests while you are rate limited may result in the banning of your integration.

For more information about how to avoid exceeding the rate limits, see "Best practices for using the REST API."

404 Not Found for an existing resource

If you make a request to access a private resource and your request isn't properly authenticated, you will receive a 404 Not Found response. GitHub uses a 404 Not Found response instead of a 403 Forbidden response to avoid confirming the existence of private repositories.

If you get a 404 Not Found response when you know that the resource that you are requesting exists, you should check your authentication. For example:

  • If you are using a personal access token, you should ensure that:
    • The token has the scopes that are required to use the endpoint. For more information, see "Scopes for OAuth apps" and "Managing your personal access tokens."
    • The owner of the token has any permissions that are required to use the endpoint. For example, if an endpoint can only be used by organization owners, only users that are owners of the affected organization can use the endpoint.
    • The token has not been expired or revoked. For more information, see "Token expiration and revocation."
  • If you are using a GitHub App installation access token, you should ensure that:
    • The GitHub App has the permissions that are required to use the endpoint. For more information, see "Permissions required for GitHub Apps."
    • The endpoint is only affecting resources owned by the account where the GitHub App is installed.
    • The GitHub App has access to any repositories that the endpoint will affect.
    • The token has not been expired or revoked. For more information, see "Token expiration and revocation."
  • If you are using a GitHub App user access token, you should ensure that:
    • The GitHub App has the permissions that are required to use the endpoint. For more information, see "Permissions required for GitHub Apps."
    • The user that authorized the token has any permissions that are required to use the endpoint. For example, if an endpoint can only be used by organization owners, only users that are owners of the affected organization can use the endpoint.
    • The GitHub App has access to any repositories that the endpoint will affect.
    • The user has access to any repositories that the endpoint will affect.
    • The user has approved any updated permissions for your GitHub App. For more information, see "Approving updated permissions for a GitHub App."
  • If you are using an OAuth app user access token, you should ensure that:
    • The token has the scopes that are required to use the endpoint. For more information, see "Scopes for OAuth apps."
    • The user that authorized the token has any permissions that are required to use the endpoint. For example, if an endpoint can only be used by organization owners, only users that are owners of the affected organization can use the endpoint.
    • The organization has not blocked OAuth app access, if you are using an endpoint that will affect resources owned by an organization. App owners cannot see whether their app is blocked, but they can instruct users of the app to check this. For more information, see "About OAuth app access restrictions" in the GitHub Free documentation.
    • The token has not been expired or revoked. For more information, see "Token expiration and revocation."
  • If you are using GITHUB_TOKEN in a GitHub Actions workflow, you should ensure that:
    • The endpoint is only affecting resources owned by the repository where the workflow is running. If you need to access resources outside of that repository, such as resources owned by an organization or resources owned by another repository, you should use a personal access token or an access token for a GitHub App.

For more information about authentication, see "Authenticating to the REST API."

You should also check for typos in your URL. For example, adding a trailing slash to the endpoint will result in a 404 Not Found. You can refer to the reference documentation for the endpoint to confirm that you have the correct URL.

Additionally, any path parameters must be URL encoded. For example, any slashes in the parameter value must be replaced with %2F. If you don't properly encode any slashes in the parameter name, the endpoint URL will be misinterpreted.

Missing results

Most endpoints that return a list of resources support pagination. For most of these endpoints, only the first 30 resources are returned by default. In order to see all of the resources, you need to paginate through the results. For more information, see "Using pagination in the REST API."

If you are using pagination correctly and still do not see all of the results that you expect, you should confirm that the authentication credentials that you used have access to all of the expected resources. For example, if you are using a GitHub App installation access token, if the installation was only granted access to a subset of repositories in an organization, any request for all repositories in that organization will return only the repositories that the app installation can access.

Timeouts

If GitHub Enterprise Server takes more than 10 seconds to process an API request, GitHub Enterprise Server will terminate the request and you will receive a timeout response and a "Server Error" message.

GitHub Enterprise Server reserves the right to change the timeout window to protect the speed and reliability of the API.

You can check the status of the REST API at githubstatus.com to determine whether the timeout is due to a problem with the API. You can also try to simplify your request or try your request later. For example, if you are requesting 100 items on a page, you can try requesting fewer items.

Resource not accessible

If you are using a GitHub App and you receive a "Resource not accessible by integration" error, then your token has insufficient permissions. For more information about the permissions required for each endpoint, see "Permissions required for GitHub Apps."

Problems parsing JSON

If you send invalid JSON in the request body, you may receive a 400 Bad Request response and a "Problems parsing JSON" error message. You can use a linter or JSON validator to help you identify errors in your JSON.

Body should be a JSON object

If the endpoint expects a JSON object and you do not format your request body as a JSON object, you may receive a 400 Bad Request response and a "Body should be a JSON object" error message.

Invalid request

If you omit required parameters or you use the wrong type for a parameter, you may receive a 422 Unprocessable Entity response and an "Invalid request" error message. For example, you will get this error if you specify a parameter value as an array but the endpoint is expecting a string. You can refer to the reference documentation for the endpoint to verify that you are using the correct parameter types and that you are including all of the required parameters.

Validation Failed

If your request could not be processed, you may receive a 422 Unprocessable Entity response and a "Validation Failed" error message. The response body will include an errors property, which includes a code property to help you diagnose the problem.

CodeDescription
missingA resource does not exist.
missing_fieldA parameter that was required was not specified. Review the documentation for the endpoint to see what parameters are required.
invalidThe formatting of a parameter is invalid. Review the endpoint documentation for more specific information.
already_existsAnother resource has the same value as one of your parameters. This can happen in resources that must have some unique key (such as label names).
unprocessableThe parameters that were provided were invalid.
customRefer to the message property to diagnose the error.

User agent required

Requests without a valid User-Agent header will be rejected. You should use your username or the name of your application for the User-Agent value.

curl sends a valid User-Agent header by default.

Other errors

If you observe an error that is not addressed here, you should refer to the error message that the API gives you. Most error messages will provide a clue about what is wrong and a link to relevant documentation.

If you observe unexpected failures, you can use githubstatus.com or the GitHub status API to check for incidents affecting the API.

Further reading