# How Resume.github.com Handles GitHub API Rate Limiting

> Learn how resume.github.com handles GitHub API rate limiting by detecting 403 errors and displaying a user-friendly notification to inform about exhausted request quotas.

- Repository: [GitHub resume generator/resume.github.com](https://github.com/resume/resume.github.com)
- Tags: internals
- Published: 2026-03-04

---

**The resume.github.com application detects GitHub API rate limiting by monitoring for HTTP 403 responses in the `github_user_starred_resume` function, propagates a sentinel string `'api_limit'` through the main execution flow, and renders a dedicated error page from [`views/api_limit.html`](https://github.com/resume/resume.github.com/blob/main/views/api_limit.html) to notify users that the request quota has been exhausted.**

The open-source resume generator at `resume/resume.github.com` constructs user résumés from GitHub profile data using client-side JavaScript. Because the application relies entirely on unauthenticated GitHub API requests—which are strictly rate-limited by IP address—it implements a specific error-handling pathway to gracefully manage quota exhaustion.

## Detecting Rate Limits in the Starred Repositories Check

The primary detection mechanism lives in the `github_user_starred_resume` function within [`js/githubresume.js`](https://github.com/resume/resume.github.com/blob/main/js/githubresume.js). This helper method queries the GitHub API for repositories a user has starred, and includes an explicit error callback that inspects the HTTP status code of failed requests.

According to the source code at lines 119–124, the Ajax configuration handles error responses as follows:

```javascript
$.ajax({
    url: url,
    async: false,
    dataType: 'json',
    success: function (data) { /* process starred repos */ },
    error: function (e) {
        if (e.status == 403) {               // rate-limit hit
            errorMsg = 'api_limit';
        } else if (e.status == 404) {
            errorMsg = 'not_found';
        }
    }
});

```

When GitHub returns a **403 Forbidden** status—indicating the hourly API quota has been exceeded—the function assigns the sentinel value `'api_limit'` to `errorMsg` and returns this string to its caller instead of repository data.

## Propagating Errors Through the Application Flow

The main entry point `run` (also in [`js/githubresume.js`](https://github.com/resume/resume.github.com/blob/main/js/githubresume.js)) invokes `github_user_starred_resume` early in the initialization sequence to validate the username and check rate limit status before attempting to render the résumé.

At lines 149–166, the code evaluates the returned value and branches accordingly:

```javascript
var starred = github_user_starred_resume(username);

if (!starred || starred === 'api_limit' || starred === 'not_found') {
    if (starred === 'api_limit') {
        // Load the rate-limit view instead of the resume template
        $.ajax({
            url: 'views/api_limit.html',
            dataType: 'html',
            success: function (data) {
                $('#resume').html(data);
            }
        });
        return;   // Halt further processing
    }
    // Handle not_found case...
}

```

This pattern ensures that **no subsequent API calls are attempted** once a rate limit is detected, preventing unnecessary network requests and providing immediate user feedback.

## Displaying the Rate Limit Warning to Users

When the `'api_limit'` sentinel triggers the error branch, the application fetches and injects the HTML fragment located at [`views/api_limit.html`](https://github.com/resume/resume.github.com/blob/main/views/api_limit.html). This file contains a concise, user-friendly explanation of the failure:

```html
<!-- views/api_limit.html -->
<p>The API rate limit has been exceeded for your IP address. Please try again later.</p>

```

This approach provides clear communication without exposing technical error details or stack traces.

## Coverage Limitations in Other API Calls

The graceful degradation for GitHub API rate limiting is **not comprehensive** across the entire codebase. While `github_user_starred_resume` explicitly handles 403 responses, other critical API helpers—including `github_user`, `github_user_repos`, and `github_user_issues`—do not implement dedicated 403 detection in this version of the source.

Consequently, if the rate limit is exhausted during these subsequent calls, the application lacks structured error handling and may fail silently or display generic error states rather than the specific rate-limit warning.

## Summary

- **Detection**: The `github_user_starred_resume` function in [`js/githubresume.js`](https://github.com/resume/resume.github.com/blob/main/js/githubresume.js) checks for HTTP 403 status codes and returns the string `'api_limit'` when hit.
- **Propagation**: The main `run` function intercepts this sentinel value and loads a specific error view rather than continuing with résumé generation.
- **Presentation**: Users see a dedicated message from [`views/api_limit.html`](https://github.com/resume/resume.github.com/blob/main/views/api_limit.html) explaining that the API quota has been exceeded for their IP address.
- **Scope**: Rate limit handling is currently limited to the starred-repository check; other API endpoints in the application lack equivalent protection.

## Frequently Asked Questions

### How does resume.github.com detect when the GitHub API rate limit is exceeded?

The application detects rate limiting by examining the HTTP status code in Ajax error callbacks. Specifically, the `github_user_starred_resume` function in [`js/githubresume.js`](https://github.com/resume/resume.github.com/blob/main/js/githubresume.js) checks if `e.status == 403` within its error handler. A 403 response from GitHub's API indicates that the unauthenticated request quota has been exhausted for the requesting IP address.

### What happens when the application detects a 403 error from the GitHub API?

When a 403 error is detected, the `github_user_starred_resume` function returns the sentinel string `'api_limit'` to the main `run` function. The `run` function then halts all further processing, fetches the HTML content from [`views/api_limit.html`](https://github.com/resume/resume.github.com/blob/main/views/api_limit.html), and injects it into the page DOM to display a friendly error message instructing the user to try again later.

### Which API calls in resume.github.com include rate limit handling?

Only the `github_user_starred_resume` function includes explicit rate limit detection. Other API helpers such as `github_user`, `github_user_repos`, and `github_user_issues` do not contain dedicated 403 handling logic, meaning the application may not gracefully handle quota exhaustion if it occurs during these subsequent requests.

### Where is the rate limit error message defined in the codebase?

The user-facing error message resides in [`views/api_limit.html`](https://github.com/resume/resume.github.com/blob/main/views/api_limit.html). This file contains a simple HTML paragraph stating: "The API rate limit has been exceeded for your IP address. Please try again later." The main application logic loads this fragment dynamically via Ajax when the `'api_limit'` sentinel is detected in the initialization flow.