Webflow Common Errors

Overview

Quick reference for the most common Webflow Data API v2 errors, their root causes, and concrete solutions. Covers every HTTP status code the API returns.

Prerequisites

• webflow-api SDK installed
• API token configured
• Access to application logs

HTTP Error Reference

400 Bad Request — Invalid Input

{ "code": "validation_error", "message": "Invalid field data" }

Common causes:

• Missing required field (name and slug are always required for CMS items)
• Wrong field type (sending string for a Number field)
• Invalid slug format (must be lowercase, hyphens only, no spaces)
• Bulk request exceeds 100 items

Fix:

// Check collection schema before creating items
const collection = await webflow.collections.get(collectionId);
const requiredFields = collection.fields?.filter(f => f.isRequired);
console.log("Required fields:", requiredFields?.map(f => `${f.slug} (${f.type})`));

// Validate slug format
function isValidSlug(slug: string): boolean {
  return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug);
}

401 Unauthorized — Invalid Token

{ "code": "unauthorized", "message": "Not authorized" }

Common causes:

• Token revoked or expired
• Token copied with extra whitespace
• Using v1 API key format with v2 endpoints

Fix:

# Verify token works
curl -s https://api.webflow.com/v2/sites \
  -H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

# Check for whitespace issues
echo -n "$WEBFLOW_API_TOKEN" | wc -c

// Programmatic token check
async function verifyToken(): Promise<boolean> {
  try {
    await webflow.sites.list();
    return true;
  } catch (err: any) {
    if (err.statusCode === 401) {
      console.error("Token invalid. Generate new token at developers.webflow.com");
      return false;
    }
    throw err;
  }
}

403 Forbidden — Missing Scope

{ "code": "forbidden", "message": "Insufficient permissions" }

Common causes:

• Token missing required scope (e.g., calling CMS write with only cms:read)
• Site token used for a different site
• OAuth app not authorized for the scope

Fix:

// Required scopes by operation
const SCOPE_MAP: Record<string, string> = {
  "sites.list": "sites:read",
  "sites.publish": "sites:write",
  "collections.list": "cms:read",
  "collections.items.createItem": "cms:write",
  "pages.list": "pages:read",
  "forms.list": "forms:read",
  "products.list": "ecommerce:read",
  "products.create": "ecommerce:write",
  "orders.list": "ecommerce:read",
  "orders.refund": "ecommerce:write",
};

Generate a new token with the correct scopes at https://developers.webflow.com.

404 Not Found — Wrong Resource ID

{ "code": "not_found", "message": "Resource not found" }

Common causes:

• Wrong site_id, collection_id, or item_id
• Resource deleted
• Using staging ID against live endpoint (or vice versa)

Fix:

// Discovery chain: always start from sites.list()
async function discoverResources() {
  const { sites } = await webflow.sites.list();
  console.log("Sites:", sites?.map(s => `${s.displayName}: ${s.id}`));

  for (const site of sites!) {
    const { collections } = await webflow.collections.list(site.id!);
    console.log(`  Collections in ${site.displayName}:`);
    for (const col of collections!) {
      console.log(`    ${col.displayName}: ${col.id}`);
    }
  }
}

409 Conflict — Duplicate Resource

{ "code": "conflict", "message": "Item with slug already exists" }

Common causes:

• CMS item with same slug already exists in collection
• Trying to create a resource that already exists

Fix:

// Check for existing slug before creating
async function createOrUpdate(collectionId: string, slug: string, fieldData: Record<string, any>) {
  const { items } = await webflow.collections.items.listItems(collectionId);
  const existing = items?.find(i => i.fieldData?.slug === slug);

  if (existing) {
    return webflow.collections.items.updateItem(collectionId, existing.id!, { fieldData });
  }
  return webflow.collections.items.createItem(collectionId, { fieldData: { slug, ...fieldData } });
}

429 Too Many Requests — Rate Limited

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Common causes:

• Exceeded per-key rate limit
• Site publish called more than once per minute
• Rapid-fire requests without throttling

Fix:

// The SDK auto-retries 429s with exponential backoff.
// For manual control:
async function waitForRateLimit(retryAfterSeconds: number) {
  console.log(`Rate limited. Waiting ${retryAfterSeconds}s...`);
  await new Promise(r => setTimeout(r, retryAfterSeconds * 1000));
}

See webflow-rate-limits for comprehensive rate limit handling.

500/502/503 — Webflow Server Error

Fix:

# 1. Check Webflow status
curl -s https://status.webflow.com/api/v2/status.json | jq '.status'

# 2. Retry with backoff (SDK handles this automatically)
# 3. If persistent, check Webflow status page and open support ticket

Quick Diagnostic Commands

# Test API connectivity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
  https://api.webflow.com/v2/sites

# Check rate limit headers
curl -v -H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
  https://api.webflow.com/v2/sites 2>&1 | grep -i "x-ratelimit\|retry-after"

# List sites (quick token verification)
curl -s -H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
  https://api.webflow.com/v2/sites | jq '.sites[].displayName'

# Check Webflow platform status
curl -s https://status.webflow.com/api/v2/status.json | jq '.status.description'

Error Handling Pattern

import { WebflowClient } from "webflow-api";

async function resilientCall<T>(
  operation: () => Promise<T>,
  label: string
): Promise<T> {
  try {
    return await operation();
  } catch (err: any) {
    const status = err.statusCode || err.status;

    const actionMap: Record<number, string> = {
      400: "Fix request payload — check field names and types",
      401: "Rotate token at developers.webflow.com",
      403: "Add missing scope to token",
      404: "Verify resource IDs with discovery chain",
      409: "Handle duplicate — update instead of create",
      429: "Wait for Retry-After header (SDK auto-retries)",
      500: "Webflow server error — retry later",
    };

    console.error(`[${label}] HTTP ${status}: ${actionMap[status] || "Unknown error"}`);
    console.error(`  Message: ${err.message}`);
    console.error(`  Body: ${JSON.stringify(err.body)}`);

    throw err;
  }
}

Escalation Path

1. Check error code against this reference
2. Run diagnostic commands above
3. Collect evidence with webflow-debug-bundle
4. Check Webflow Status
5. Open support ticket with request ID and error details

Output

• Identified error cause from HTTP status code
• Applied targeted fix
• Verified resolution

Resources

• Webflow API Error Codes
• Webflow Status Page
• Rate Limits Reference

Next Steps

For comprehensive debugging, see webflow-debug-bundle.