Webflow Rate Limits

Overview

Handle Webflow Data API v2 rate limits using the SDK's built-in retry, manual backoff strategies, request queuing, and bulk endpoints to maximize throughput without hitting 429 errors.

Prerequisites

• webflow-api

  SDK installed
• Understanding of async/await patterns
• Knowledge of your site plan's rate limits

Webflow Rate Limit Rules

Per-Key Rate Limits

Rate limits are applied per API key (not per site or per user). Each token has its own independent rate limit counter.

triggerType

Rate Limit Response Headers

X-RateLimit-Limit

X-RateLimit-Remaining

Retry-After

429 Response

{
  "code": "rate_limit",
  "message": "Rate limit exceeded. Please retry after 60 seconds."
}

Instructions

Step 1: SDK Built-In Retry

The

webflow-api

import { WebflowClient } from "webflow-api";

const webflow = new WebflowClient({
  accessToken: process.env.WEBFLOW_API_TOKEN!,
  maxRetries: 3, // Default: 2. SDK uses exponential backoff.
});

// The SDK handles 429s transparently — no extra code needed
const { sites } = await webflow.sites.list();

Step 2: Manual Exponential Backoff with Jitter

For operations outside the SDK or when you need custom retry logic:

async function withBackoff<T>(
  operation: () => Promise<T>,
  config = {
    maxRetries: 5,
    baseDelayMs: 1000,
    maxDelayMs: 60000,
    jitterMs: 500,
  }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      const status = error.statusCode || error.status;

      // Only retry on 429 (rate limit) and 5xx (server errors)
      if (attempt === config.maxRetries) throw error;
      if (status !== 429 && (status < 500 || status >= 600)) throw error;

      // Honor Retry-After header if present
      const retryAfter = error.headers?.get?.("Retry-After");
      let delay: number;

      if (retryAfter) {
        delay = parseInt(retryAfter) * 1000;
      } else {
        // Exponential backoff with jitter to prevent thundering herd
        const exponential = config.baseDelayMs * Math.pow(2, attempt);
        const jitter = Math.random() * config.jitterMs;
        delay = Math.min(exponential + jitter, config.maxDelayMs);
      }

      console.log(`Rate limited (attempt ${attempt + 1}). Retrying in ${delay}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error("Unreachable");
}

// Usage
const items = await withBackoff(() =>
  webflow.collections.items.listItems(collectionId)
);

Step 3: Request Queue with Concurrency Control

Use

p-queue

import PQueue from "p-queue";

// Webflow rate limits reset every 60 seconds
// Adjust concurrency based on your plan's limit
const queue = new PQueue({
  concurrency: 5,       // Max parallel requests
  interval: 1000,       // Time window (ms)
  intervalCap: 10,      // Max requests per interval
});

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

// Usage — requests are automatically queued and throttled
const results = await Promise.all(
  collectionIds.map(id =>
    queuedRequest(() => webflow.collections.items.listItems(id))
  )
);

Step 4: Use Bulk Endpoints to Reduce Request Count

A single bulk request counts as one rate limit hit but handles up to 100 items:

// BAD: 100 individual requests = 100 rate limit counts
for (const item of items) {
  await webflow.collections.items.createItem(collectionId, { fieldData: item });
}

// GOOD: 1 bulk request = 1 rate limit count
await webflow.collections.items.createItemsBulk(collectionId, {
  items: items.slice(0, 100).map(item => ({ fieldData: item })),
});

Available bulk endpoints:

• createItemsBulk

  — Create up to 100 items

• updateItemsBulk

  — Update up to 100 items

• deleteItemsBulk

  — Delete up to 100 items

• publishItem

  — Publish multiple items by ID

Step 5: Rate Limit Monitor

Track rate limit usage across your application:

class RateLimitMonitor {
  private remaining = Infinity;
  private limit = 0;
  private resetAt: Date = new Date();

  updateFromHeaders(headers: Headers) {
    const remaining = headers.get("X-RateLimit-Remaining");
    const limit = headers.get("X-RateLimit-Limit");
    const retryAfter = headers.get("Retry-After");

    if (remaining) this.remaining = parseInt(remaining);
    if (limit) this.limit = parseInt(limit);
    if (retryAfter) {
      this.resetAt = new Date(Date.now() + parseInt(retryAfter) * 1000);
    }
  }

  shouldThrottle(): boolean {
    return this.remaining < 5 && new Date() < this.resetAt;
  }

  async waitIfNeeded(): Promise<void> {
    if (this.shouldThrottle()) {
      const waitMs = Math.max(0, this.resetAt.getTime() - Date.now());
      console.log(`Throttling: waiting ${waitMs}ms for rate limit reset`);
      await new Promise(r => setTimeout(r, waitMs));
    }
  }

  getStatus() {
    return {
      remaining: this.remaining,
      limit: this.limit,
      resetAt: this.resetAt.toISOString(),
      throttled: this.shouldThrottle(),
    };
  }
}

Step 6: Batch Processing Large Datasets

For operations involving thousands of items:

async function processLargeDataset(
  collectionId: string,
  allItems: Array<Record<string, any>>,
  batchSize = 100,
  delayBetweenBatchesMs = 1000
) {
  const results = { created: 0, failed: 0, errors: [] as any[] };

  for (let i = 0; i < allItems.length; i += batchSize) {
    const batch = allItems.slice(i, i + batchSize);
    const batchNum = Math.floor(i / batchSize) + 1;
    const totalBatches = Math.ceil(allItems.length / batchSize);

    try {
      await withBackoff(() =>
        webflow.collections.items.createItemsBulk(collectionId, {
          items: batch.map(item => ({ fieldData: item, isDraft: false })),
        })
      );
      results.created += batch.length;
      console.log(`Batch ${batchNum}/${totalBatches}: ${batch.length} items created`);
    } catch (error) {
      results.failed += batch.length;
      results.errors.push({ batch: batchNum, error });
    }

    // Delay between batches to stay within rate limits
    if (i + batchSize < allItems.length) {
      await new Promise(r => setTimeout(r, delayBetweenBatchesMs));
    }
  }

  return results;
}

Output

• SDK auto-retry configured for 429 errors
• Manual backoff with Retry-After header support
• Request queue with concurrency control
• Bulk endpoints reducing request count by 100x
• Rate limit monitoring and adaptive throttling

Error Handling

Resources

• Rate Limits Reference
• Bulk CMS Endpoints
• p-queue Documentation

Next Steps

For security configuration, see

webflow-security-basics