Get Started

Rate Limits & Tiers

— Fixed windows, honest headers, graceful backoff.

Every /api/v1 request passes through a rate limiter. On the FREE tier you are limited per IP; with an API key you are limited per key. Limits are advisory headers on every response, so a well-behaved client never has to guess.

How It Works

Each identity (IP or key) gets a request budget per fixed time window.
Every response includes X-RateLimit-* headers describing the current window.
Exceeding the budget returns 429 with a Retry-After header.

Limits by Tier

The FREE window is 60 requests per 60 seconds per IP. Keyed tiers raise the ceiling.

Tier	Type	Description
Free	per IP	60 requests / 60s. No key required.
Build	per key	Higher sustained rate for application backends.
Scale	per key	Production throughput with a wider burst window.
Staked	$PLUID	Ceiling scales with held $PLUID. See the token page.

Want more headroom without a plan

Holding $PLUID raises your limits directly. Authentication details are in Authentication.

Response Headers

Header	Type	Description
X-RateLimit-Limit	int	Total requests allowed in the window.
X-RateLimit-Remaining	int	Requests remaining before a 429.
X-RateLimit-Reset	epoch s	Unix seconds when the window resets.
Retry-After	seconds	On 429 only — seconds to wait before retrying.

Handling a 429

When you exceed the window, Pluid returns a structured error. Back off until Retry-After elapses, then resume.

json

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Hold $PLUID for higher limits."
}

backoff.tsts

async function read(url: string): Promise<Response> {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, { headers: { "x-api-key": process.env.PLUID_API_KEY! } });
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get("Retry-After") ?? 1) * 1000;
    if (attempt >= 5) return res;
    await new Promise((r) => setTimeout(r, wait));
  }
}

Prefer the headers over retries

Read X-RateLimit-Remaining on each response and slow down before you hit zero. Reactive backoff on 429 is a safety net, not a strategy.

PreviousAuthentication ReferenceREST API