FireCrawl レート制限

概要

エクスポーネンシャルバックオフとベき等性を使用して、FireCrawl レート制限を優雅に処理します。

前提条件

• FireCrawl SDK がインストールされていること
• async/await パターンの理解
• レート制限ヘッダーへのアクセス

説明

ステップ 1: レート制限ティアを理解する

ティア	リクエスト/分	リクエスト/日	バースト
Free	60	1,000	10
Pro	300	10,000	50
Enterprise	1,000	100,000	200

ステップ 2: ジッターを伴うエクスポーネンシャルバックオフを実装する

async function withExponentialBackoff<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 32000, jitterMs: 500 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      if (attempt === config.maxRetries) throw error;
      const status = error.status || error.response?.status;
      if (status !== 429 && (status < 500 || status >= 600)) throw error;

      // Exponential delay with jitter to prevent thundering herd
      const exponentialDelay = config.baseDelayMs * Math.pow(2, attempt);
      const jitter = Math.random() * config.jitterMs;
      const delay = Math.min(exponentialDelay + jitter, config.maxDelayMs);

      console.log(`Rate limited. Retrying in ${delay.toFixed(0)}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

ステップ 3: ベき等性キーを追加する

import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';

// Generate deterministic key from operation params (for safe retries)
function generateIdempotencyKey(operation: string, params: Record<string, any>): string {
  const data = JSON.stringify({ operation, params });
  return crypto.createHash('sha256').update(data).digest('hex');
}

async function idempotentRequest<T>(
  client: FireCrawlClient,
  params: Record<string, any>,
  idempotencyKey?: string  // Pass existing key for retries
): Promise<T> {
  // Use provided key (for retries) or generate deterministic key from params
  const key = idempotencyKey || generateIdempotencyKey(params.method || 'POST', params);
  return client.request({
    ...params,
    headers: { 'Idempotency-Key': key, ...params.headers },
  });
}

出力

• 自動リトライ機能付きの信頼性の高い API 呼び出し
• 重複を防ぐベき等なリクエスト
• レート制限ヘッダーの適切な処理

エラーハンドリング

ヘッダー	説明	アクション
X-RateLimit-Limit	最大リクエスト数	使用状況を監視
X-RateLimit-Remaining	残りリクエスト数	少ない場合はスロットル
X-RateLimit-Reset	リセットタイムスタンプ	リセットまで待機
Retry-After	待機秒数	この値を守る

例

キューベースのレート制限

import PQueue from 'p-queue';

const queue = new PQueue({
  concurrency: 5,
  interval: 1000,
  intervalCap: 10,
});

async function queuedRequest<T>(operation: () => Promise<T>): Promise<T> {
  return queue.add(operation);
}

レート制限の使用状況を監視する

class RateLimitMonitor {
  private remaining: number = 60;
  private resetAt: Date = new Date();

  updateFromHeaders(headers: Headers) {
    this.remaining = parseInt(headers.get('X-RateLimit-Remaining') || '60');
    const resetTimestamp = headers.get('X-RateLimit-Reset');
    if (resetTimestamp) {
      this.resetAt = new Date(parseInt(resetTimestamp) * 1000);
    }
  }

  shouldThrottle(): boolean {
    // Only throttle if low remaining AND reset hasn't happened yet
    return this.remaining < 5 && new Date() < this.resetAt;
  }

  getWaitTime(): number {
    return Math.max(0, this.resetAt.getTime() - Date.now());
  }
}

リソース

• FireCrawl Rate Limits
• p-queue Documentation

次のステップ

セキュリティ設定については、firecrawl-security-basics を参照してください。