Rate limits

Two-tier, plan-aware. Per-key buckets protect you from a single misbehaving script; the workspace ceiling protects the cluster from a customer minting many keys.

The buckets

Every API request hits two buckets. A request is allowed only when both have headroom.

Headers

Every response (success or 429) carries the rate-limit triplet:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1745842800

• Limit — max requests in the current 60-second window
• Remaining — requests left in this window (≥ 0)
• Reset — unix-seconds when the window resets

When the binding bucket is the workspace ceiling, the headers reflect that bucket — not the per-key one — because that's what you need to back off on.

429 responses

When you exceed a bucket:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1745842800
Content-Type: application/json

{ "error": "RATE_LIMIT_EXCEEDED", "bucket": "per-key" }

Retry-After is in seconds, always ≥ 1. The bucket field is one of per-key or workspace so you know whether to slow down a single consumer or coordinate across all your keys.

Backoff strategy

We recommend a token-bucket client that:

1. Reads X-RateLimit-Remaining on every response.
2. Throttles new sends when Remaining drops below 10% of Limit.
3. On 429, sleeps Retry-After seconds and retries with jitter.
4. Retries idempotent requests (GET, PUT, DELETE) up to 3 times. POST requests should NOT be auto-retried unless you supply an Idempotency-Key header (coming in a future release).

Need higher limits?

Email hello@lazynext.com with your use case. Enterprise contracts can lift the ceiling.