134 lines
8.8 KiB
Markdown
134 lines
8.8 KiB
Markdown
---
|
|
title: Rate limits for the REST API
|
|
shortTitle: Rate limits
|
|
intro: 'Learn about REST API rate limits, how to avoid exceeding them, and what to do if you do exceed them.'
|
|
versions:
|
|
fpt: '*'
|
|
ghes: '*'
|
|
ghec: '*'
|
|
topics:
|
|
- API
|
|
redirect_from:
|
|
- /rest/overview/rate-limits-for-the-rest-api
|
|
---
|
|
|
|
{% ifversion ghes %}
|
|
|
|
Rate limits are disabled by default for {% data variables.product.prodname_ghe_server %}. Contact your site administrator to confirm the rate limits for your instance.
|
|
|
|
If you are a site administrator, you can set rate limits, including secondary rate limits, for your instance. See [AUTOTITLE](/admin/configuration/configuring-user-applications-for-your-enterprise/configuring-rate-limits).
|
|
|
|
If you are developing an app for users or organizations outside of your instance, the standard {% data variables.product.github %} rate limits apply. See [AUTOTITLE](/free-pro-team@latest/rest/overview/rate-limits-for-the-rest-api) in the {% data variables.product.prodname_free_user %} documentation.
|
|
|
|
## About secondary rate limits
|
|
|
|
{% data reusables.rest-api.secondary-rate-limit-rest-graphql %}
|
|
|
|
{% else %}
|
|
|
|
## About primary rate limits
|
|
|
|
{% data variables.product.company_short %} limits the number of REST API requests that you can make within a specific amount of time. This limit helps prevent abuse and denial-of-service attacks, and ensures that the API remains available for all users.
|
|
|
|
Some endpoints, like the search endpoints, have more restrictive limits. For more information about these endpoints, see [AUTOTITLE](/rest/rate-limit/rate-limit). The GraphQL API also has a separate primary rate limit. See [AUTOTITLE](/graphql/overview/resource-limitations).
|
|
|
|
{% data reusables.organizations.api-insights-learn-about %}
|
|
|
|
In general, you can calculate your primary rate limit for the REST API based on your method of authentication, as described below.
|
|
|
|
### Primary rate limit for unauthenticated users
|
|
|
|
{% data reusables.rest-api.primary-rate-limit-unauthenticated-users %}
|
|
|
|
### Primary rate limit for authenticated users
|
|
|
|
{% data reusables.rest-api.primary-rate-limit-authenticated-users %}
|
|
|
|
{% ifversion ghec %}
|
|
> [!NOTE]
|
|
> The [Enterprise audit logs API endpoint](/rest/enterprise-admin/audit-log#get-the-audit-log-for-an-enterprise) has a rate limit of 1,750 queries per hour, per user and IP address. If your integration receives a rate limit error (typically a 403 or 429 response), it should wait before making another request to the GitHub API.
|
|
{% endif %}
|
|
|
|
### Primary rate limit for Git LFS access
|
|
|
|
API requests are required when you upload or download Git LFS content. These count towards a separate rate limiting bucket with a limit of 300 requests per minute for unauthenticated requests and 3,000 requests per minute for authenticated requests.
|
|
|
|
Git LFS uses a batch API which processes 100 Git LFS objects per API request by default. That means unauthenticated users can download 30,000 Git LFS objects per minute and authenticated users can upload/download 300,000 Git LFS objects per minute.
|
|
|
|
### Primary rate limit for {% data variables.product.prodname_github_app %} installations
|
|
|
|
{% data reusables.rest-api.primary-rate-limit-github-app-installations %}
|
|
|
|
### Primary rate limit for {% data variables.product.prodname_oauth_apps %}
|
|
|
|
Primary rate limits for OAuth access tokens generated by a {% data variables.product.prodname_oauth_app %} are dictated by the primary rate limits for authenticated users. This rate limit is combined with any requests that another {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %} makes on that user's behalf and any requests that the user makes with a {% data variables.product.pat_generic %}. See [Primary rate limit for authenticated users](#primary-rate-limit-for-authenticated-users).
|
|
|
|
OAuth apps can also use their client ID and client secret to fetch public data. For example:
|
|
|
|
```shell
|
|
curl -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET -I {% data variables.product.rest_url %}/meta
|
|
```
|
|
|
|
{% data reusables.rest-api.primary-rate-limit-oauth-apps %}
|
|
|
|
> [!NOTE]
|
|
> Never include your app's client secret in client-side code or in code that runs on a user device. The client secret can be used to generate OAuth access tokens for users who have authorized your app, so you should always keep the client secret secure.
|
|
|
|
### Primary rate limit for `GITHUB_TOKEN` in {% data variables.product.prodname_actions %}
|
|
|
|
You can use the built-in `GITHUB_TOKEN` to authenticate requests in {% data variables.product.prodname_actions %} workflows. See [AUTOTITLE](/actions/security-guides/automatic-token-authentication).
|
|
|
|
{% data reusables.rest-api.primary-rate-limit-github-token-in-actions %}
|
|
|
|
## About secondary rate limits
|
|
|
|
{% data reusables.rest-api.secondary-rate-limit-rest-graphql %}
|
|
|
|
## Checking the status of your rate limit
|
|
|
|
You can use the headers that are sent with each response to determine the current status of your primary rate limit.
|
|
|
|
Header name | Description
|
|
-----------|-----------|
|
|
`x-ratelimit-limit` | The maximum number of requests that you can make per hour
|
|
`x-ratelimit-remaining` | The number of requests remaining in the current rate limit window
|
|
`x-ratelimit-used` | The number of requests you have made in the current rate limit window
|
|
`x-ratelimit-reset` | The time at which the current rate limit window resets, in UTC epoch seconds
|
|
`x-ratelimit-resource` | The rate limit resource that the request counted against. For more information about the different resources, see [AUTOTITLE](/rest/rate-limit/rate-limit#get-rate-limit-status-for-the-authenticated-user).
|
|
|
|
You can also call the `GET /rate_limit` endpoint to check your rate limit. Calling this endpoint does not count against your primary rate limit, but it can count against your secondary rate limit. See [AUTOTITLE](/rest/rate-limit/rate-limit). When possible, you should use the rate limit response headers instead of calling the API to check your rate limit.
|
|
|
|
There is not a way to check the status of your secondary rate limit.
|
|
|
|
## Exceeding the rate limit
|
|
|
|
If you exceed your primary rate limit, you will receive a `403` or `429` response, and the `x-ratelimit-remaining` header will be `0`. You should not retry your request until after the time specified by the `x-ratelimit-reset` header.
|
|
|
|
If you exceed a secondary rate limit, you will receive a `403` or `429` response and an error message that indicates that you exceeded a secondary rate limit. 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 retry your request until after the time, in UTC epoch seconds, specified by the `x-ratelimit-reset` header. 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.
|
|
|
|
## Staying under the rate limit
|
|
|
|
You should follow best practices to help you stay under the rate limits. See [AUTOTITLE](/rest/guides/best-practices-for-using-the-rest-api).
|
|
|
|
{% ifversion ghec or ghes %}
|
|
|
|
You can also stream the audit log in order to view API requests. This can help you troubleshoot integrations that are exceeding the rate limit. See [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise).
|
|
|
|
{% endif %}
|
|
|
|
## Getting a higher rate limit
|
|
|
|
If you want a higher primary rate limit, consider making authenticated requests instead of unauthenticated requests. Authenticated requests have a significantly higher rate limit than unauthenticated requests.
|
|
|
|
If you are using a {% data variables.product.pat_generic %} for automation in your organization, consider whether a {% data variables.product.prodname_github_app %} will work instead.{% ifversion fpt %} The rate limit for {% data variables.product.prodname_github_apps %} using an installation access token scales with the number of repositories and number of organization users.{% endif %}{% ifversion ghec %} {% data variables.product.prodname_github_apps %} used by {% data variables.product.prodname_ghe_cloud %} accounts have a higher rate limit than {% data variables.product.pat_generic_plural %}.{% endif %} See [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps).
|
|
|
|
{% ifversion fpt %}
|
|
|
|
If you are using {% data variables.product.prodname_github_apps %} or {% data variables.product.prodname_oauth_apps %}, consider upgrading to {% data variables.product.prodname_ghe_cloud %}. {% data variables.product.prodname_github_apps %} or {% data variables.product.prodname_oauth_apps %} have higher rate limits for organizations that use {% data variables.product.prodname_ghe_cloud %}.
|
|
|
|
{% endif %}
|
|
|
|
{% endif %}
|