Flexport Rate Limits

Flexport Rate Limits

Overview

The Flexport API v2 enforces rate limits per API key. When exceeded, you get a 429 Too Many Requests with Retry-After and X-RateLimit-* headers. Key limits to know: the API returns headers on every response telling you remaining quota.

Prerequisites

• Current account limits confirmed from the provider, with a named concurrency/budget owner and reviewed exception queue.
• Aggregate telemetry that excludes shipment records, documents, commercial terms, and credentials.
• Sandbox fixtures that exercise throttling, pause/retry, and duplicate prevention.

Output

Produce a rate-control receipt with policy version, concurrency, retry bound, throttle count, queue age, idempotency outcome, and manual dispositions. Do not log payloads or headers containing secrets.

Examples

Run a fictional shipment event under a low concurrency limit, simulate a 429, and confirm the worker honors its bounded wait and processes the opaque event once after recovery. Repeated failures enter review rather than causing a bulk replay.

Rate Limit Headers

Instructions

Step 1: Monitor Rate Limit Headers

class RateLimitTracker {
  remaining = Infinity;
  resetAt = 0;

  update(headers: Headers) {
    this.remaining = parseInt(headers.get('X-RateLimit-Remaining') || '100');
    this.resetAt = parseInt(headers.get('X-RateLimit-Reset') || '0') * 1000;
  }

  async waitIfNeeded() {
    if (this.remaining <= 2 && Date.now() < this.resetAt) {
      const wait = this.resetAt - Date.now() + 100;
      console.log(`Rate limit near. Waiting ${wait}ms`);
      await new Promise(r => setTimeout(r, wait));
    }
  }
}

Step 2: Exponential Backoff with Jitter

async function flexportWithRetry<T>(
  fn: () => Promise<Response>,
  maxRetries = 4
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fn();

    if (res.ok) return res.json();

    if (res.status === 429) {
      const retryAfter = parseInt(res.headers.get('Retry-After') || '60');
      const jitter = Math.random() * 2000;
      const delay = retryAfter * 1000 + jitter;
      console.log(`429 rate limited. Retry in ${(delay / 1000).toFixed(1)}s`);
      await new Promise(r => setTimeout(r, delay));
      continue;
    }

    if (res.status >= 500 && attempt < maxRetries) {
      const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
      await new Promise(r => setTimeout(r, delay));
      continue;
    }

    throw new Error(`Flexport ${res.status}: ${await res.text()}`);
  }
  throw new Error('Max retries exceeded');
}

Step 3: Queue-Based Throttling

import PQueue from 'p-queue';

// Limit to 10 requests per second with max 3 concurrent
const flexportQueue = new PQueue({
  concurrency: 3,
  interval: 1000,
  intervalCap: 10,
});

async function throttledRequest(path: string): Promise<any> {
  return flexportQueue.add(() =>
    fetch(`https://api.flexport.com${path}`, {
      headers: {
        'Authorization': `Bearer ${process.env.FLEXPORT_API_KEY}`,
        'Flexport-Version': '2',
      },
    }).then(r => r.json())
  );
}

// Bulk operations stay within limits
const shipmentIds = ['shp_001', 'shp_002', 'shp_003', /* ... */];
const results = await Promise.all(
  shipmentIds.map(id => throttledRequest(`/shipments/${id}`))
);

Error Handling

Resources

• Flexport API Reference
• p-queue

Next Steps

For security configuration, see flexport-security-basics.