feat: auto retry rate limit (#53)

* feat: automatically retry 429 and 5xx responses

Bake rate-limit (429) and server-error (5xx) retry/back-off into the
request layer so callers no longer need their own retry loops.

- 429s are retried indefinitely, respecting the Retry-After header
  (falling back to retryAfterFallback seconds when absent). Applies to
  all methods, since a 429 is rejected before processing.
- 5xx errors are retried up to maxServerErrorRetries times (default 5)
  for GET only, since writes may not be idempotent. The last Response is
  returned once retries are exhausted, keeping the existing return
  contract intact.
- Every retry is re-scheduled through the limiter, with random jitter
  added to each wait.
- Configurable (and disablable) via the new `retry` setting.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: FreekBes

README.md

@@ -7,6 +7,7 @@ Features:
 - Automatically determines the rate limit of your API key.
 - Queues requests (using bottleneck)
 - Multi-key support (be carefull, it might be too fast! 🚀)
+- Automatic retries on rate-limit (429) and server (5xx) errors, with back-off.
 - Convenience: fetch all pages from an endpoint with a single method call!
 - Clustering (v2.1 and up): using Redis you can run multiple instances on the same API keys!
 
@@ -22,6 +23,7 @@ interface Fast42Settings {
     jobExpiration?: number; // default is 60000ms, especially important when using redis to kill infinite jobs
     redisConfig?: RedisConfig; // config to connect to redis, see below
     scopes?: string[]; // default is ['public', 'projects']
+    retry?: RetryConfig; // automatic retry behaviour, see below
 }
 
 interface ApiSecret {
@@ -33,6 +35,13 @@ interface RedisConfig {
     port: number;
     password?: string;
 }
+interface RetryConfig {
+    enabled?: boolean; // master switch, default is true
+    maxServerErrorRetries?: number; // max retries on 5xx errors per request, default is 5. 429s are always retried indefinitely.
+    serverErrorBackoff?: number; // base ms to wait before retrying a 5xx error, default is 30000
+    retryAfterFallback?: number; // seconds to wait on a 429 when no Retry-After header is present, default is 1
+    jitter?: number; // max random extra ms added to every retry wait, default is 10000
+}
 
 // Always call .init() first after constructing Fast42!
 init(): Promise<Fast42>
@@ -89,6 +98,29 @@ const pages = await api.getAllPages(`/campus/${campus_id}/users`, {
 
 Obviously your id/secret should come from the environment and not be committed to git. (I recommend using a `.env` file and the `dotenv` package)
 
+### Retries
+
+The rate limiter does its best to stay under your key's limits, but the 42 API counts requests on its own clock, so an occasional `429 Too Many Requests` can still slip through (especially when running multiple instances). Fast42 therefore retries automatically:
+
+- **429 (rate limit):** retried indefinitely, waiting for the duration of the `Retry-After` header (or `retryAfterFallback` seconds when it is absent). Applies to every request, including writes — a 429 is rejected before processing, so it is always safe to retry.
+- **5xx (server error):** retried up to `maxServerErrorRetries` times (default 5), waiting `serverErrorBackoff` ms between attempts. Only `GET` requests are retried on 5xx, since writes (`post`/`put`/`patch`/`delete`) may not be idempotent. After the retries are exhausted the last `Response` is returned, so existing `.ok`/`.status` checks keep working.
+
+Every retry goes back through the rate limiter, and a random `jitter` (up to 10s by default) is added to each wait to spread retries out. Retries can be tuned or disabled via the `retry` setting:
+
+```ts
+const api = await new Fast42([{ client_id, client_secret }], {
+  retry: {
+    enabled: true,            // set to false to get the raw Response back without retrying
+    maxServerErrorRetries: 3,
+    serverErrorBackoff: 30000,
+    retryAfterFallback: 1,
+    jitter: 10000,
+  },
+}).init();
+```
+
+This means your own code generally no longer needs a 429/5xx retry loop around `get`/`getAllPages`.
+
 How I use it:
 
 ```ts
@@ -123,17 +155,12 @@ async function getAll42(
 
   // Attach a callback function to be called when the page promise resolves
   return Promise.all(pages.map(async (page) => {
-    let p = await page;
+    const p = await page;
     const pagenr = getPageNumberFromUrl(p.url);
-    // retry when the ratelimit was hit
-    // (this can happen because the timing on 42api side is different from the timing of the Fast42 ratelimiter)
-    if (p.status === 429) {
-      if (pagenr) {
-        p = await api.getPage(url, pagenr, options);
-      } else {
-        console.error(`Failed retry on unkown page for ${url}`);
-      }
-    }
+    // No manual 429 retry needed: Fast42 retries rate-limited (429) requests
+    // automatically, so any page we get here has already passed the rate limiter.
+    // (This used to be required because the timing on the 42api side differs from
+    // the timing of the Fast42 ratelimiter.)
     if (p.ok) {
       console.log(`Recieved ${url} page: ${pagenr}`);
       return callback(p);

src/index.ts

@@ -40,11 +40,29 @@ interface RedisConfig {
   password?: string;
 }
 
+interface RetryConfig {
+  /** Master switch for automatic retries. Default: true. */
+  enabled?: boolean;
+  /**
+   * Maximum number of retries for 5xx server errors (per request).
+   * 429 rate-limit responses are always retried, indefinitely, respecting Retry-After.
+   * Default: 5.
+   */
+  maxServerErrorRetries?: number;
+  /** Base delay in ms to wait before retrying a 5xx server error. Default: 30000. */
+  serverErrorBackoff?: number;
+  /** Delay in seconds to wait on a 429 when the Retry-After header is missing. Default: 1. */
+  retryAfterFallback?: number;
+  /** Maximum random extra delay in ms added to every retry wait (spreads out retries). Default: 10000. */
+  jitter?: number;
+}
+
 interface Fast42Settings {
   concurrentOffset?: number;
   jobExpiration?: number;
   redisConfig?: RedisConfig;
   scopes?: string[];
+  retry?: RetryConfig;
 }
 
 enum Method {
@@ -67,6 +85,7 @@ class Fast42 {
   private _redisConfig: RedisConfig | undefined;
   private _jobExpiration: number;
   private _scopes: string[];
+  private _retry: Required<RetryConfig>;
 
   /**
    * Constructs the api42 class
@@ -108,6 +127,13 @@ class Fast42 {
     this._redisConfig = settings.redisConfig
     this._jobExpiration = settings.jobExpiration ?? 60000
     this._scopes = settings.scopes ?? ['public', 'projects']
+    this._retry = {
+      enabled: settings.retry?.enabled ?? true,
+      maxServerErrorRetries: settings.retry?.maxServerErrorRetries ?? 5,
+      serverErrorBackoff: settings.retry?.serverErrorBackoff ?? 30000,
+      retryAfterFallback: settings.retry?.retryAfterFallback ?? 1,
+      jitter: settings.retry?.jitter ?? 10000,
+    }
   }
 
   /*
@@ -285,35 +311,71 @@ class Fast42 {
 
 
   private async apiReq(method: Method.GET, limiterPair: LimiterPair, url: string): Promise<Response> {
-    const accessToken = await this.retrieveToken(limiterPair.tokenIndex)
-    const response = limiterPair.limiter.schedule(
-      limiterPair.jobOptions,
-      (accessToken, url) => {
-        return fetch(url, {
-          method: method,
-          headers: {
-            Authorization: `Bearer ${accessToken.access_token}`
-          }
-        })
-      }, accessToken, url)
-    return response
+    // GET requests are idempotent, so it is safe to retry them on server errors as well.
+    return this.scheduleWithRetry(limiterPair, true, async () => {
+      const accessToken = await this.retrieveToken(limiterPair.tokenIndex)
+      return fetch(url, {
+        method: method,
+        headers: {
+          Authorization: `Bearer ${accessToken.access_token}`
+        }
+      })
+    })
   }
 
   private async apiReqWithBody(method: Method.PATCH | Method.POST | Method.PUT | Method.DELETE, limiterPair: LimiterPair, url: string, body: any): Promise<Response> {
-    const accessToken = await this.retrieveToken(limiterPair.tokenIndex)
-    const response = limiterPair.limiter.schedule(
-      limiterPair.jobOptions,
-      (accessToken, url, body) => {
-        return fetch(url, {
-          method: method,
-          headers: {
-            'Authorization': `Bearer ${accessToken.access_token}`,
-            'Content-Type': 'application/json',
-          },
-          body: JSON.stringify(body),
-        })
-      }, accessToken, url, body)
-    return response
+    // Writes may not be idempotent, so we only retry rate-limit (429) responses (which are
+    // rejected before processing and therefore safe to retry), not 5xx server errors.
+    return this.scheduleWithRetry(limiterPair, false, async () => {
+      const accessToken = await this.retrieveToken(limiterPair.tokenIndex)
+      return fetch(url, {
+        method: method,
+        headers: {
+          'Authorization': `Bearer ${accessToken.access_token}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+      })
+    })
+  }
+
+  /**
+   * Schedules a request on the given limiter and transparently retries it on rate-limit (429)
+   * and, optionally, server-error (5xx) responses. Each (re)try goes through the limiter again,
+   * so the rate limiter keeps accounting for retried requests.
+   *
+   * 429 responses are retried indefinitely, waiting for the duration of the Retry-After header
+   * (falling back to retryAfterFallback seconds when absent). 5xx responses are retried up to
+   * maxServerErrorRetries times when retryServerErrors is true. After exhausting the 5xx retries,
+   * the last response is returned so the caller can inspect it (the return contract is unchanged).
+   */
+  private async scheduleWithRetry(limiterPair: LimiterPair, retryServerErrors: boolean, job: () => Promise<Response>): Promise<Response> {
+    let serverErrorRetries = 0
+    while (true) {
+      const response: Response = await limiterPair.limiter.schedule(limiterPair.jobOptions, job)
+
+      if (this._retry.enabled && response.status === 429) {
+        const retryAfterHeader = parseInt(response.headers.get('retry-after') ?? '')
+        const retryAfter = Number.isNaN(retryAfterHeader) ? this._retry.retryAfterFallback : retryAfterHeader
+        await this.delay(retryAfter * 1000 + Math.random() * this._retry.jitter)
+        continue
+      }
+
+      if (this._retry.enabled && retryServerErrors && response.status >= 500 && response.status < 600) {
+        if (serverErrorRetries >= this._retry.maxServerErrorRetries) {
+          return response
+        }
+        serverErrorRetries++
+        await this.delay(this._retry.serverErrorBackoff + Math.random() * this._retry.jitter)
+        continue
+      }
+
+      return response
+    }
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
   }
 
   private parseOptions(options: { [key: string]: string } | undefined): string {

tests/index.test.ts

@@ -93,6 +93,120 @@ it("Should use configured scopes when requesting access token", async () => {
     );
 })
 
+describe("scheduleWithRetry", () => {
+    // A fake limiter that just runs the scheduled job immediately, so we can test the
+    // retry logic without spinning up a real Bottleneck instance or hitting the network.
+    const fakeLimiterPair = (job: () => Promise<any>) => ({
+        appId: 1,
+        limiter: { schedule: (_opts: any, fn: () => Promise<any>) => fn() },
+        secret: { client_id, client_secret },
+        tokenIndex: 0,
+        jobOptions: {},
+        _job: job,
+    });
+
+    // Minimal stand-in for a node-fetch Response.
+    const res = (status: number, retryAfter?: string) => ({
+        status,
+        ok: status >= 200 && status < 300,
+        headers: { get: (h: string) => (h.toLowerCase() === 'retry-after' ? (retryAfter ?? null) : null) },
+    });
+
+    // No real waiting between retries.
+    const noWaitRetry = { serverErrorBackoff: 0, retryAfterFallback: 0, jitter: 0, maxServerErrorRetries: 2 };
+
+    const newApi = (retry: any = noWaitRetry) =>
+        new Fast42([{ client_id, client_secret }], { retry });
+
+    it("retries a 429 until it succeeds, respecting Retry-After", async () => {
+        const responses = [res(429, '0'), res(429, '0'), res(200)];
+        const job = jest.fn(async () => responses.shift());
+        const pair = fakeLimiterPair(job);
+
+        const result = await (newApi() as any).scheduleWithRetry(pair, true, job);
+
+        expect(result.status).toBe(200);
+        expect(job).toHaveBeenCalledTimes(3);
+    });
+
+    it("retries 5xx errors up to maxServerErrorRetries then returns the last response", async () => {
+        const job = jest.fn(async () => res(503));
+        const pair = fakeLimiterPair(job);
+
+        const result = await (newApi() as any).scheduleWithRetry(pair, true, job);
+
+        expect(result.status).toBe(503);
+        expect(job).toHaveBeenCalledTimes(3); // 1 initial + 2 retries
+    });
+
+    it("does not retry 5xx errors when retryServerErrors is false (e.g. writes)", async () => {
+        const job = jest.fn(async () => res(503));
+        const pair = fakeLimiterPair(job);
+
+        const result = await (newApi() as any).scheduleWithRetry(pair, false, job);
+
+        expect(result.status).toBe(503);
+        expect(job).toHaveBeenCalledTimes(1);
+    });
+
+    it("still retries 429 for writes (retryServerErrors false)", async () => {
+        const responses = [res(429, '0'), res(201)];
+        const job = jest.fn(async () => responses.shift());
+        const pair = fakeLimiterPair(job);
+
+        const result = await (newApi() as any).scheduleWithRetry(pair, false, job);
+
+        expect(result.status).toBe(201);
+        expect(job).toHaveBeenCalledTimes(2);
+    });
+
+    it("does not retry when retries are disabled", async () => {
+        const job = jest.fn(async () => res(429, '0'));
+        const pair = fakeLimiterPair(job);
+
+        const result = await (newApi({ enabled: false }) as any).scheduleWithRetry(pair, true, job);
+
+        expect(result.status).toBe(429);
+        expect(job).toHaveBeenCalledTimes(1);
+    });
+
+    it("returns 2xx responses immediately without retrying", async () => {
+        const job = jest.fn(async () => res(200));
+        const pair = fakeLimiterPair(job);
+
+        const result = await (newApi() as any).scheduleWithRetry(pair, true, job);
+
+        expect(result.status).toBe(200);
+        expect(job).toHaveBeenCalledTimes(1);
+    });
+
+    it("returns non-retryable 4xx responses immediately", async () => {
+        const job = jest.fn(async () => res(404));
+        const pair = fakeLimiterPair(job);
+
+        const result = await (newApi() as any).scheduleWithRetry(pair, true, job);
+
+        expect(result.status).toBe(404);
+        expect(job).toHaveBeenCalledTimes(1);
+    });
+});
+
+it("Should default retry settings to enabled with bounded 5xx retries", () => {
+    const api = new Fast42([
+        {
+            client_id: client_id,
+            client_secret: client_secret,
+        },
+    ]);
+    expect((api as any)._retry).toEqual({
+        enabled: true,
+        maxServerErrorRetries: 5,
+        serverErrorBackoff: 30000,
+        retryAfterFallback: 1,
+        jitter: 10000,
+    });
+})
+
 // it("initializes using real keys", async () => {
 //     const api = await (new Fast42([
 //         {