What are GitHub Rate Limits?

GitHub uses rate limits to control the number of requests made to its servers within a specific time period. This mechanism is in place to prevent abuse, ensure fair usage for all users, and maintain the stability and performance of the platform. When the number of requests from an IP address or an authenticated user exceeds the defined threshold within the given time frame, subsequent requests are temporarily blocked, resulting in a rate limit error.

Types of GitHub Rate Limits

GitHub applies different types of rate limits depending on the type of request and whether the request is authenticated.

• API Rate Limits: Apply to requests made through the GitHub REST API and GraphQL API.
  • Unauthenticated Requests: Requests made without an access token or other form of authentication have a lower rate limit, typically 60 requests per hour per IP address.
  • Authenticated Requests: Requests made with a personal access token, OAuth token, or GitHub App installation access token have significantly higher rate limits, typically 5,000 requests per hour per authenticated user or application.
• Git Rate Limits: Apply to operations performed using the Git protocol, such as cloning, fetching, or pushing repositories. These limits are typically based on the volume of operations per hour per IP address or authenticated user.

How to Check Rate Limit Status

Understanding the current rate limit status is crucial for diagnosing and handling rate limit errors.

• Checking API Rate Limits: The current rate limit status for the GitHub API can be checked using a dedicated endpoint. A simple curl command can retrieve this information:

  curl -i https://api.github.com/rate_limit
  

  For authenticated limits, include an authentication token:

  curl -i -H "Authorization: token YOUR_TOKEN" https://api.github.com/rate_limit
  

  The response headers provide key information:

  • X-RateLimit-Limit: The maximum number of requests allowed in the current time window.
  • X-RateLimit-Remaining: The number of requests remaining in the current window.
  • X-RateLimit-Reset: The Unix timestamp when the current window resets and the rate limit is refreshed.

• Checking Rate Limits from API Responses: Every response from the GitHub API includes the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers, allowing monitoring of the rate limit status with each request.

• Checking Git Rate Limits: Git rate limits are not exposed via a dedicated API endpoint in the same way as API limits. Errors related to Git limits are typically indicated by messages received during Git operations (e.g., cloning, fetching, pushing) from the Git client or server.

Common Causes of GitHub Rate Limit Errors

Several scenarios can lead to encountering GitHub rate limits:

• Unauthenticated API Usage: Running scripts or applications that make many API calls without authenticating quickly exhausts the low limit for unauthenticated requests.
• Aggressive Scripting or Automation: Bots, scripts, or automation tools (like CI/CD pipelines) making a large volume of requests within a short period, especially if not optimized to handle limits.
• Heavy Cloning or Fetching: Repeatedly cloning or fetching large repositories or a large number of repositories from the same IP address or using the same credentials.
• Misconfigured Clients: Applications or tools that do not correctly handle redirects, retry logic, or conditional requests, leading to excessive or redundant requests.
• Shared IP Addresses: Multiple users or processes behind a single IP address (e.g., within a company network or using a shared hosting service) contributing to the same unauthenticated rate limit bucket.

Strategies to Avoid or Handle Rate Limits

Dealing with GitHub rate limits effectively involves both preventative measures and reactive handling.

• Authenticate Requests: The most effective way to increase rate limits is to authenticate API requests. Using personal access tokens for personal scripts or OAuth tokens/GitHub App installation tokens for applications increases the limit to 5,000 requests per hour per identity.
• Use Conditional Requests: For API calls fetching resource details, utilize the If-None-Match header with the ETag value from a previous response. If the resource has not changed, GitHub returns a 304 Not Modified status without counting towards the rate limit.
• Implement Caching: Cache API responses locally or in memory where possible to avoid repeatedly fetching the same data within a short timeframe.
• Handle Rate Limit Responses Gracefully: When a rate limit error (typically HTTP status code 403 with a specific error message or a 429 Too Many Requests) is received:
  • Check the X-RateLimit-Reset header to determine when the limit resets.
  • Pause subsequent requests until the reset time.
  • Implement a waiting and retry strategy (e.g., exponential backoff) rather than immediately retrying the failed request.
• Reduce the Number of Requests: Optimize workflows to make fewer requests. Can multiple pieces of information be fetched in a single request? Is all the data truly necessary?
• Utilize GitHub Apps: GitHub Apps have higher rate limits than user-based personal access tokens and are the recommended way to build integrations that interact with GitHub APIs on behalf of many users or organizations.
• Leverage GitHub Actions: Workflows running within GitHub Actions benefit from higher rate limits when interacting with the GitHub API via the built-in GITHUB_TOKEN. This token has permissions scoped to the repository and workflow and comes with generous rate limits.
• Optimize Git Operations: For Git operations, avoid unnecessary clones or fetches. Use shallow clones (git clone --depth 1) if only the latest history is needed. Consider caching Git repositories if performing repeated operations on the same repo.