Handling API Rate Limiting Gracefully in TypeScript Projects

When working with APIs, hitting a rate limit is common. APIs often restrict how many requests you can make in a given time frame to protect their servers. If you exceed this limit, you'll get an error response, usually with status code 429. Handling this properly helps your application stay reliable and polite to the API.

In this beginner-friendly guide, we'll cover how to catch rate limiting errors and retry your request after a delay using TypeScript.

### What is Rate Limiting?

Rate limiting is a control mechanism used by APIs to limit the number of requests a client can make in a certain period. For example, an API may allow 100 requests per minute. If you go beyond this, it returns a 429 Too Many Requests status code.

### Handling 429 Errors Gracefully

When you receive a 429 error, the API may send a `Retry-After` header indicating how long to wait before trying again. If this header is missing, you can implement a default wait time or use exponential backoff.

Here is a simple example of how to handle rate limiting using TypeScript with the Fetch API and exponential backoff:

async function fetchWithRateLimit(url: string, retries = 3, delay = 1000): Promise<any> {
  try {
    const response = await fetch(url);

    if (response.status === 429) {
      if (retries > 0) {
        // Check for Retry-After header
        const retryAfter = response.headers.get('Retry-After');
        const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : delay;
        console.warn(`Rate limited. Retrying after ${waitTime} ms...`);
        await new Promise(res => setTimeout(res, waitTime));
        // Retry with exponential backoff
        return fetchWithRateLimit(url, retries - 1, delay * 2);
      } else {
        throw new Error('Rate limit exceeded. Max retries reached');
      }
    }

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Fetch failed:', error);
    throw error;
  }
}

### How It Works

1. We attempt to fetch the resource. 2. If the response status is 429, and retries remain, check the `Retry-After` header. 3. Wait for the indicated time or a default delay. 4. Retry the request, doubling the delay each time to reduce request frequency. 5. If all retries fail, throw an error. 6. Handle other HTTP errors and successful responses normally.

### Tips for Beginners

- Always respect the API's rate limits to avoid being blocked. - Use the `Retry-After` header if provided. - Keep retry attempts limited to avoid infinite loops. - Inform users of delays or failures gracefully in your UI.

Handling API rate limiting gracefully not only improves your app's stability but also helps maintain a good relationship with the API provider. Using this pattern in your TypeScript projects will make your API requests smarter and more resilient.