Linktree Rate Limits

Overview

Linktree's API enforces rate limits per OAuth token, with analytics endpoints throttled more aggressively than profile management operations. Agencies managing dozens of creator profiles need to stagger link updates and analytics pulls across accounts to avoid hitting per-token and global IP-based limits. Bulk link reordering and analytics export during campaign launches are the most common rate-limit triggers, especially when synchronizing link performance data with external dashboards on short polling intervals.

Rate Limit Reference

Rate Limiter Implementation

class LinktreeRateLimiter {
  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 linkLimiter = new LinktreeRateLimiter(25);
const analyticsLimiter = new LinktreeRateLimiter(8);

Retry Strategy

async function linktreeRetry<T>(
  limiter: LinktreeRateLimiter, 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") || "30", 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) * 1500));
      continue;
    }
    throw new Error(`Linktree API ${res.status}: ${await res.text()}`);
  }
  throw new Error("Max retries exceeded");
}

Batch Processing

async function batchUpdateLinks(profileId: string, links: any[], batchSize = 5) {
  const results: any[] = [];
  for (let i = 0; i < links.length; i += batchSize) {
    const batch = links.slice(i, i + batchSize);
    const batchResults = await Promise.all(
      batch.map(link => linktreeRetry(linkLimiter, () =>
        fetch(`${BASE}/api/v1/profiles/${profileId}/links/${link.id}`, {
          method: "PATCH", headers,
          body: JSON.stringify({ title: link.title, url: link.url }),
        })
      ))
    );
    results.push(...batchResults);
    if (i + batchSize < links.length) await new Promise(r => setTimeout(r, 10_000));
  }
  return results;
}

Error Handling

Resources

• Linktree Developer Documentation

Next Steps

See linktree-performance-tuning.