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.

Rate Limit Headers

Header	Description	Example
X-RateLimit-Limit	Max requests per window	100
X-RateLimit-Remaining	Remaining in current window	47
X-RateLimit-Reset	Unix timestamp when window resets	1711234567
Retry-After	Seconds to wait (only on 429)	30

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

Scenario	Strategy
Single 429	Honor Retry-After header
Repeated 429s	Increase backoff, reduce concurrency
Bulk import	Use p-queue with intervalCap
Batch reads	Paginate with per=100 to minimize calls

Resources

• Flexport API Reference
• p-queue

Next Steps

For security configuration, see flexport-security-basics.