juicebox-rate-limits

Juicebox Rate Limits

Overview

Implement production-grade rate limiting for Juicebox API integrations. Covers parsing rate limit headers from every response, a token bucket rate limiter that respects server-reported limits, exponential backoff with jitter for 429 recovery, a priority request queue for bulk sourcing operations, and real-time quota tracking across search and enrichment endpoints.

Prerequisites

• Juicebox API credentials configured (JUICEBOX_USERNAME, JUICEBOX_API_TOKEN)
• Node.js 18+ (uses native fetch and Headers)
• Understanding of Juicebox's rate limit tiers (varies by plan)
• curl available for inspecting rate limit headers

Instructions

Step 1: Parse Rate Limit Headers

Every Juicebox API response includes three rate limit headers. Parse them on every response to maintain a live view of your remaining quota.

// lib/rate-limit-headers.ts
export interface RateLimitState {
  limit: number;         // Max requests allowed per window
  remaining: number;     // Requests left in current window
  resetAt: Date;         // When the window resets (UTC)
  retryAfter: number;    // Seconds to wait (only present on 429)
}

export function parseRateLimitHeaders(headers: Headers): RateLimitState {
  return {
    limit: parseInt(headers.get("X-RateLimit-Limit") ?? "100", 10),
    remaining: parseInt(headers.get("X-RateLimit-Remaining") ?? "100", 10),
    resetAt: new Date(
      parseInt(headers.get("X-RateLimit-Reset") ?? String(Date.now() / 1000), 10) * 1000
    ),
    retryAfter: parseInt(headers.get("Retry-After") ?? "0", 10),
  };
}

export function shouldThrottle(state: RateLimitState): boolean {
  // Proactively throttle when below 10% remaining
  return state.remaining < state.limit * 0.1;
}

export function msUntilReset(state: RateLimitState): number {
  return Math.max(0, state.resetAt.getTime() - Date.now());
}

Verify headers against the live API:

# Inspect rate limit headers on a real request
curl -s -D - \
  -H "Authorization: token ${JUICEBOX_USERNAME}:${JUICEBOX_API_TOKEN}" \
  "https://api.juicebox.ai/api/v1/search?q=engineer&limit=1" \
  | grep -iE "x-ratelimit|retry-after"

Step 2: Build a Token Bucket Rate Limiter

The token bucket algorithm smooths out burst traffic and respects the server's reported limit. When a response arrives, update the bucket with the server's X-RateLimit-Remaining value to stay synchronized.

// lib/token-bucket.ts
export class TokenBucketRateLimiter {
  private tokens: number;
  private lastRefill: number;
  private readonly refillRate: number; // tokens per millisecond

  constructor(
    private readonly maxTokens: number,
    windowMs: number = 60_000 // default: 1 minute window
  ) {
    this.tokens = maxTokens;
    this.lastRefill = Date.now();
    this.refillRate = maxTokens / windowMs;
  }

  private refill(): void {
    const now = Date.now();
    const elapsed = now - this.lastRefill;
    this.tokens = Math.min(this.maxTokens, this.tokens + elapsed * this.refillRate);
    this.lastRefill = now;
  }

  async acquire(): Promise<void> {
    this.refill();

    if (this.tokens >= 1) {
      this.tokens -= 1;
      return;
    }

    // Wait until one token is available
    const waitMs = (1 - this.tokens) / this.refillRate;
    await new Promise((resolve) => setTimeout(resolve, Math.ceil(waitMs)));
    this.tokens -= 1;
  }

  // Sync with server-reported state after each response
  syncWithServer(state: RateLimitState): void {
    this.tokens = state.remaining;
    this.lastRefill = Date.now();
  }

  get availableTokens(): number {
    this.refill();
    return Math.floor(this.tokens);
  }
}

Step 3: Add Exponential Backoff with Jitter

When a 429 does arrive, use exponential backoff with full jitter to avoid thundering herd problems when multiple clients retry simultaneously.

// lib/backoff.ts
export interface BackoffOptions {
  maxRetries: number;
  baseDelayMs: number;
  maxDelayMs: number;
  jitter: boolean;
}

const DEFAULT_BACKOFF: BackoffOptions = {
  maxRetries: 5,
  baseDelayMs: 1000,
  maxDelayMs: 60_000,
  jitter: true,
};

export async function withExponentialBackoff<T>(
  fn: () => Promise<Response>,
  options: Partial<BackoffOptions> = {}
): Promise<Response> {
  const opts = { ...DEFAULT_BACKOFF, ...options };

  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
    const response = await fn();

    if (response.ok) return response;

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get("Retry-After") ?? "0", 10);

      // Use server's Retry-After if provided, otherwise calculate backoff
      let delayMs: number;
      if (retryAfter > 0) {
        delayMs = retryAfter * 1000;
      } else {
        delayMs = Math.min(
          opts.baseDelayMs * Math.pow(2, attempt),
          opts.maxDelayMs
        );
      }

      // Add jitter: random value between 0 and delayMs
      if (opts.jitter) {
        delayMs = Math.floor(Math.random() * delayMs);
      }

      console.warn(
        `[Juicebox] 429 rate limited. Attempt ${attempt + 1}/${opts.maxRetries}. ` +
        `Waiting ${delayMs}ms before retry.`
      );

      if (attempt < opts.maxRetries) {
        await new Promise((resolve) => setTimeout(resolve, delayMs));
        continue;
      }
    }

    // Non-429 error or exhausted retries
    if (attempt === opts.maxRetries) {
      throw new Error(
        `Juicebox API request failed after ${opts.maxRetries} retries. ` +
        `Last status: ${response.status}`
      );
    }
  }

  throw new Error("Unreachable");
}

Step 4: Implement a Priority Request Queue

For bulk operations (e.g., sourcing 500 candidates), queue requests with priorities so critical lookups skip ahead of background enrichments.

// lib/request-queue.ts
import { TokenBucketRateLimiter } from "./token-bucket";
import { parseRateLimitHeaders } from "./rate-limit-headers";
import { withExponentialBackoff } from "./backoff";

type Priority = "critical" | "normal" | "background";

interface QueuedRequest<T> {
  priority: Priority;
  execute: () => Promise<Response>;
  resolve: (value: T) => void;
  reject: (error: Error) => void;
}

const PRIORITY_ORDER: Record<Priority, number> = {
  critical: 0,
  normal: 1,
  background: 2,
};

export class RateLimitedQueue {
  private queue: QueuedRequest<Response>[] = [];
  private processing = false;
  private readonly limiter: TokenBucketRateLimiter;

  constructor(requestsPerMinute: number) {
    this.limiter = new TokenBucketRateLimiter(requestsPerMinute);
  }

  async enqueue(
    execute: () => Promise<Response>,
    priority: Priority = "normal"
  ): Promise<Response> {
    return new Promise<Response>((resolve, reject) => {
      this.queue.push({ priority, execute, resolve, reject });
      // Sort by priority after insertion
      this.queue.sort(
        (a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority]
      );
      this.processQueue();
    });
  }

  private async processQueue(): Promise<void> {
    if (this.processing || this.queue.length === 0) return;
    this.processing = true;

    while (this.queue.length > 0) {
      await this.limiter.acquire();

      const item = this.queue.shift()!;
      try {
        const response = await withExponentialBackoff(item.execute);
        // Sync rate limiter with server state
        const state = parseRateLimitHeaders(response.headers);
        this.limiter.syncWithServer(state);
        item.resolve(response);
      } catch (error) {
        item.reject(error as Error);
      }
    }

    this.processing = false;
  }

  get pendingCount(): number {
    return this.queue.length;
  }
}

Step 5: Track Quota Across Endpoints

Different Juicebox endpoints may have separate rate limits. Track quota per-endpoint to avoid one category of requests starving another.

// lib/quota-tracker.ts
import { RateLimitState, parseRateLimitHeaders } from "./rate-limit-headers";

type Endpoint = "search" | "profiles" | "enrichments";

export class QuotaTracker {
  private state = new Map<Endpoint, RateLimitState>();
  private dailyCounts = new Map<Endpoint, number>();
  private resetTime: Date;

  constructor() {
    this.resetTime = this.nextMidnightUTC();
  }

  updateFromResponse(endpoint: Endpoint, headers: Headers): void {
    const state = parseRateLimitHeaders(headers);
    this.state.set(endpoint, state);
    this.incrementDaily(endpoint);
  }

  getEndpointState(endpoint: Endpoint): RateLimitState | undefined {
    return this.state.get(endpoint);
  }

  canMakeRequest(endpoint: Endpoint): boolean {
    const state = this.state.get(endpoint);
    if (!state) return true; // No data yet, allow
    return state.remaining > 0;
  }

  getDailySummary(): Record<Endpoint, number> {
    this.maybeResetDaily();
    return Object.fromEntries(this.dailyCounts) as Record<Endpoint, number>;
  }

  getFullReport(): string {
    const lines: string[] = ["=== Juicebox Quota Report ==="];
    for (const endpoint of ["search", "profiles", "enrichments"] as Endpoint[]) {
      const state = this.state.get(endpoint);
      const daily = this.dailyCounts.get(endpoint) ?? 0;
      if (state) {
        lines.push(
          `${endpoint}: ${state.remaining}/${state.limit} remaining ` +
          `(resets ${state.resetAt.toISOString()}) — ${daily} calls today`
        );
      } else {
        lines.push(`${endpoint}: no data yet — ${daily} calls today`);
      }
    }
    return lines.join("\n");
  }

  private incrementDaily(endpoint: Endpoint): void {
    this.maybeResetDaily();
    this.dailyCounts.set(endpoint, (this.dailyCounts.get(endpoint) ?? 0) + 1);
  }

  private maybeResetDaily(): void {
    if (Date.now() > this.resetTime.getTime()) {
      this.dailyCounts.clear();
      this.resetTime = this.nextMidnightUTC();
    }
  }

  private nextMidnightUTC(): Date {
    const d = new Da

---

*Content truncated.*