jackwener/OpenCLI · warning · CommandExecutionError

${label} returned HTTP 429 (rate limited). Lichess throttles

Error message

${label} returned HTTP 429 (rate limited). Lichess throttles anonymous traffic at ~60 req/min; back off and retry.

What it means

This CommandExecutionError is thrown by `lichessFetch` when the Lichess API responds with HTTP 429 (Too Many Requests). Lichess rate-limits anonymous traffic (~60 req/min); the library surfaces this with advice to back off and retry.

Source

Thrown at clis/lichess/utils.js:73

    return n;
}

export async function lichessFetch(url, label) {
    let resp;
    try {
        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
    }
    catch (err) {
        throw new CommandExecutionError(
            `${label} request failed: ${err?.message ?? err}`,
            'Check that lichess.org is reachable from this network.',
        );
    }
    if (resp.status === 404) {
        throw new EmptyResultError(label, `Lichess returned 404 for ${url}.`);
    }
    if (resp.status === 429) {
        throw new CommandExecutionError(
            `${label} returned HTTP 429 (rate limited)`,
            'Lichess throttles anonymous traffic at ~60 req/min; back off and retry.',
        );
    }
    if (!resp.ok) {
        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}`);
    }
    let body;
    try {
        body = await resp.json();
    }
    catch (err) {
        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
    }
    return body;
}

/** Format a lichess unix-ms timestamp as ISO date (YYYY-MM-DD). `null` when missing. */

View on GitHub (pinned to 49907e53dc)

Solutions

Add delay between requests and retry with exponential backoff honoring Retry-After
Cache responses to avoid re-fetching the same data
Authenticate with an OAuth token if you need higher limits, and still throttle
Reduce request volume: batch or filter the entities you query
Retry later if on a shared IP — the limit is per-IP for anonymous traffic

Example fix

// before
for (const n of names) await user(n); // bursts past 60 req/min
// after
for (const n of names) {
  await user(n);
  await new Promise(r => setTimeout(r, 1100)); // stay under ~60 req/min
}

Defensive patterns

Strategy: retry

Validate before calling

// Self-throttle before each call to stay under ~60 req/min
class Limiter {
  constructor(ms = 1100) { this.ms = ms; }
  async wait() { await new Promise(r => setTimeout(r, this.ms)); }
}
const limiter = new Limiter();
await limiter.wait();
await user(name);

Try / catch

async function withBackoff(fn, retries = 4) {
  for (let i = 0; ; i++) {
    try { return await fn(); }
    catch (e) {
      const is429 = e instanceof CommandExecutionError && /429/.test(e.message);
      if (!is429 || i >= retries) throw e;
      await new Promise(r => setTimeout(r, 2 ** i * 1000));
    }
  }
}
const profile = await withBackoff(() => user(name));

Prevention

Space requests ~1s apart to stay under the ~60 req/min anonymous cap
Never retry 429s in a tight loop — use exponential backoff
Cache API responses to avoid redundant lookups
Add jitter when running many parallel workers on one IP
Note shared CI/office egress IPs count toward the same limit

When it happens

Trigger: Any command routed through `lichessFetch` after exceeding Lichess's rate limit — e.g. looping over many usernames without delay, or sharing an IP (CI runner, office NAT) that already hit the anonymous cap.

Common situations: Batch scripts iterating many players with no sleep; retry loops without backoff amplifying the limit; shared CI egress IPs; multiple tools hammering the API concurrently.

Understand the failure class

HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/16e9d68f9a515ae9. Report an issue: GitHub.