All pages
Rate limits
Every marketplace endpoint is rate limited with escalating backoff: each 429 response adds a strike to the caller’s bucket, each strike doubles the required wait time, and 8 consecutive strikes lock the bucket for 1 hour. When your client honors Retry-After, strikes decay automatically as subsequent requests succeed after the window resets.
Buckets and limits
| Bucket | Limit | Window |
|---|---|---|
Token endpoint, per client_id | 30 | 60 s |
Token endpoint and /v1/* pre-introspection, per IP | 60 | 60 s |
GET /v1/*, per installation | 300 | 60 s |
Writes (PATCH /v1/installations/{id}, POST /v1/blocks/refresh), per installation | 60 | 60 s |
POST /v1/usage-events, per installation | 120 | 60 s |
| Chat tool invokes, per installation | 60 | 60 s |
| Channel inbound messages, per installation | 600 | 60 s |
| New channel Visitors, per installation | 100 | 3600 s |
| Block sessions and block events, per IP | 120 | 60 s |
What a refusal looks like
HTTP/1.1 429 Too Many Requests
Retry-After: 8
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1757793680
{ "error": "rate_limited", "retry_after": 8, "backoff": 8, "strike": 3, "locked": false }retry_after is authoritative: at least the remainder of the current window, doubling on each strike (2^strike seconds with 0–25% jitter), capped at 15 minutes (900 seconds), and 3600 seconds when locked is true. Every successful response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset so your client can pace requests before hitting a 429.
Reference client
TypeScript / Node.js:
type Fetch = typeof fetch;
export class CravingClient {
private pausedUntil = 0;
constructor(
private token: string,
private fetchImpl: Fetch = fetch,
) {}
async request(url: string, init: RequestInit = {}, attempt = 0): Promise<Response> {
const wait = this.pausedUntil - Date.now();
if (wait > 0) await sleep(wait);
const res = await this.fetchImpl(url, {
...init,
headers: { ...init.headers, Authorization: `Bearer ${this.token}` },
});
const remaining = Number(res.headers.get('X-RateLimit-Remaining'));
const reset = Number(res.headers.get('X-RateLimit-Reset'));
if (remaining === 0 && reset > 0) this.pausedUntil = reset * 1000;
if (res.status !== 429) return res;
const body = (await res.json().catch(() => ({}))) as {
retry_after?: number;
locked?: boolean;
};
const retryAfter =
Number(res.headers.get('Retry-After')) || body.retry_after || 2 ** (attempt + 1);
if (body.locked || attempt >= 4) {
throw new Error(`rate limited; retry after ${retryAfter}s`);
}
this.pausedUntil = Date.now() + retryAfter * 1000 + Math.random() * 250;
return this.request(url, init, attempt + 1);
}
}
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));Python:
import random
import time
import requests
class CravingClient:
def __init__(self, token: str):
self.token = token
self.paused_until = 0.0
def request(self, method: str, url: str, attempt: int = 0, **kwargs) -> requests.Response:
wait = self.paused_until - time.time()
if wait > 0:
time.sleep(wait)
headers = {**kwargs.pop("headers", {}), "Authorization": f"Bearer {self.token}"}
res = requests.request(method, url, headers=headers, timeout=10, **kwargs)
if res.headers.get("X-RateLimit-Remaining") == "0":
self.paused_until = float(res.headers.get("X-RateLimit-Reset", 0))
if res.status_code != 429:
return res
body = res.json() if res.content else {}
retry_after = int(
res.headers.get("Retry-After") or body.get("retry_after") or 2 ** (attempt + 1)
)
if body.get("locked") or attempt >= 4:
raise RuntimeError(f"rate limited; retry after {retry_after}s")
self.paused_until = time.time() + retry_after + random.random() * 0.25
return self.request(method, url, attempt + 1, **kwargs)Key rules encoded in this client:
- Inspect
X-RateLimit-Remainingon every response and pause untilX-RateLimit-Resetwhen remaining hits0. - Honor
Retry-After, adding small random jitter so concurrent workers do not wake at the exact same millisecond. - Stop immediately when
locked: true: a 1-hour lock means a caller bug needs fixing, not tight retries. - Serialize writes (
POST /v1/usage-events,PATCH /v1/installations/{id}) through a queue per installation to smooth out bursts.
Rate limiting requests from craving
Our delivery workers honor your 429 responses too: when a webhook or channel.send request receives 429 with Retry-After, craving waits at least that duration before retrying. Return 429 with Retry-After during traffic spikes rather than 5xx.