lucidchart-rate-limits

Lucidchart Rate Limits

Overview

Lucidchart's API enforces per-OAuth-token rate limits, with document mutation operations (creating shapes, updating pages, modifying text) throttled more aggressively than read-only document listing. Automations that programmatically generate architecture diagrams or org charts from external data sources can easily exceed write limits when placing dozens of shapes and connectors in a single batch. Image export endpoints carry additional latency due to server-side rendering, making export-heavy workflows the most common throttling bottleneck.

Rate Limit Reference

Endpoint	Limit	Window	Scope
List documents	120 req	1 minute	Per OAuth token
Get document / pages	60 req	1 minute	Per OAuth token
Create/update shapes	30 req	1 minute	Per OAuth token
Export to PNG/PDF	10 req	1 minute	Per OAuth token
Create document	15 req	1 minute	Per OAuth token

Rate Limiter Implementation

class LucidRateLimiter {
  private tokens: number;
  private lastRefill: number;
  private readonly max: number;
  private readonly refillRate: number;
  private queue: Array<{ resolve: () => void }> = [];

  constructor(maxPerMinute: number) {
    this.max = maxPerMinute;
    this.tokens = maxPerMinute;
    this.lastRefill = Date.now();
    this.refillRate = maxPerMinute / 60_000;
  }

  async acquire(): Promise<void> {
    this.refill();
    if (this.tokens >= 1) { this.tokens -= 1; return; }
    return new Promise(resolve => this.queue.push({ resolve }));
  }

  private refill() {
    const now = Date.now();
    this.tokens = Math.min(this.max, this.tokens + (now - this.lastRefill) * this.refillRate);
    this.lastRefill = now;
    while (this.tokens >= 1 && this.queue.length) {
      this.tokens -= 1;
      this.queue.shift()!.resolve();
    }
  }
}

const writeLimiter = new LucidRateLimiter(25);
const exportLimiter = new LucidRateLimiter(8);

Retry Strategy

async function lucidRetry<T>(
  limiter: LucidRateLimiter, fn: () => Promise<Response>, maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    await limiter.acquire();
    const res = await fn();
    if (res.ok) return res.json();
    if (res.status === 429) {
      const retryAfter = parseInt(res.headers.get("Retry-After") || "20", 10);
      const jitter = Math.random() * 2000;
      await new Promise(r => setTimeout(r, retryAfter * 1000 + jitter));
      continue;
    }
    if (res.status >= 500 && attempt < maxRetries) {
      await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 2000));
      continue;
    }
    throw new Error(`Lucidchart API ${res.status}: ${await res.text()}`);
  }
  throw new Error("Max retries exceeded");
}

Batch Processing

async function batchCreateShapes(docId: string, pageId: string, shapes: any[], batchSize = 5) {
  const results: any[] = [];
  for (let i = 0; i < shapes.length; i += batchSize) {
    const batch = shapes.slice(i, i + batchSize);
    const batchResults = await Promise.all(
      batch.map(shape => lucidRetry(writeLimiter, () =>
        fetch(`${LUCID_BASE}/documents/${docId}/pages/${pageId}/shapes`, {
          method: "POST", headers,
          body: JSON.stringify(shape),
        })
      ))
    );
    results.push(...batchResults);
    if (i + batchSize < shapes.length) await new Promise(r => setTimeout(r, 8000));
  }
  return results;
}

Error Handling

Issue	Cause	Fix
429 on shape creation	Exceeded 30 writes/min token limit	Batch shapes, space 3s apart
429 on PNG export	Export limit (10/min) is very low	Queue exports with 8s spacing
408 on large document	Export rendering timeout	Request single page, not full doc
401 token expired	OAuth token TTL exceeded	Refresh token before batch operations
409 concurrent edit	Another user editing same page	Retry after 5s with fresh page version

Resources

• Lucid Developer Portal

Next Steps

See lucidchart-performance-tuning.