jackwener/OpenCLI · warning · CommandExecutionError

coingecko derivatives returned HTTP 429 (rate limited)

Error message

coingecko derivatives returned HTTP 429 (rate limited)

What it means

This CommandExecutionError is thrown when the CoinGecko /derivatives endpoint responds with HTTP 429, meaning the client has exceeded the free-tier rate limit (~30 calls/min). A remediation hint is included as the error's second argument.

Source

Thrown at clis/coingecko/derivatives.js:44

    columns: ['rank', 'market', 'symbol', 'indexId', 'contractType', 'price', 'change24hPct', 'fundingRate', 'openInterestUsd', 'volume24hUsd', 'expired'],
    func: async (args) => {
        const limit = Number(args.limit ?? 20);
        if (!Number.isInteger(limit) || limit <= 0) {
            throw new ArgumentError('coingecko derivatives limit must be a positive integer');
        }
        if (limit > 500) {
            throw new ArgumentError('coingecko derivatives limit must be <= 500');
        }
        const filter = args.symbol == null ? '' : String(args.symbol).trim().toUpperCase();
        let resp;
        try {
            resp = await fetch(ENDPOINT, { headers: { 'User-Agent': 'Mozilla/5.0' } });
        }
        catch (err) {
            throw new CommandExecutionError(`coingecko derivatives request failed: ${err?.message ?? err}`);
        }
        if (resp.status === 429) {
            throw new CommandExecutionError(
                'coingecko derivatives returned HTTP 429 (rate limited)',
                'Free tier allows ~30 calls/min. Wait and retry.',
            );
        }
        if (!resp.ok) {
            throw new CommandExecutionError(`coingecko derivatives returned HTTP ${resp.status}`);
        }
        let data;
        try {
            data = await resp.json();
        }
        catch (err) {
            throw new CommandExecutionError(`coingecko derivatives returned malformed JSON: ${err?.message ?? err}`);
        }
        if (!Array.isArray(data) || !data.length) {
            throw new EmptyResultError('coingecko derivatives', 'CoinGecko returned no derivative tickers.');
        }
        let rows = data;

View on GitHub (pinned to 49907e53dc)

Solutions

1. Wait at least 60 seconds and retry with backoff
2. Add throttling (e.g. 2s sleep between calls) or an exponential backoff/retry loop in scripts
3. Upgrade to a paid CoinGecko plan with an API key for higher limits
4. Cache responses to reduce duplicate calls

Example fix

// before
while (true) { cli derivatives } // hammers API
// after
// throttle calls
await sleep(2000);
cli derivatives --limit 20

// detect 429 and back off
if (resp.status === 429) {
  const retryAfter = Number(resp.headers.get('retry-after') ?? 60);
  await new Promise(r => setTimeout(r, retryAfter * 1000));
  resp = await fetch(ENDPOINT); // retry once
}

When it happens

Trigger: Making more than ~30 requests per minute to CoinGecko's free API; tight polling loops or many concurrent invocations of the derivatives command.

Common situations: Scripts polling in a loop without delay, CI jobs running many lookups in parallel, shared IP (VPN/CI runner) already rate-limited by other users.

Understand the failure class

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

Related errors

• coingecko returned HTTP 429 (rate limited)
• ${label} returned HTTP 429 (rate limited)
• hf spaces returned HTTP 429 (rate limited)
• ${label} returned HTTP 429 (rate limited)
• ${label} returned HTTP 429 (rate limited)

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