Rate limits

Each API key has a token-bucket rate limit. Sustained RPS is the refill rate; burst is the bucket capacity — you can briefly exceed the sustained rate until the bucket drains. We always return Retry-After on a 429, so honest backoff is straightforward.

Per-plan limits

Plan	Sustained (req/sec)	Burst (bucket capacity)
Free	1	5
Starter	5	10
Growth	20	40
Scale	60	120
Enterprise	500	1,000

Burst capacity is max(rps × 2, 5). The bucket refills continuously at the sustained rate.

Response headers

Every response includes the rate-limit headers so you can track headroom without waiting for a 429.

http

X-RateLimit-Limit: 40
X-RateLimit-Remaining: 34
Retry-After: 2

Retry-After is only present on 429 responses.

Handling 429s

Honor Retry-After. A reasonable default is exponential backoff bounded by the header value — don't sleep less than what we tell you to.

retry.mjs

async function callWithRetry(body, attempt = 0) {
  const res = await fetch("https://api.mentionsapi.com/v1/ask", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MENTIONSAPI_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (res.status === 429 && attempt < 4) {
    const retryAfter = Number(res.headers.get("Retry-After") ?? 1);
    const delay = Math.max(retryAfter * 1000, 2 ** attempt * 500);
    await new Promise((r) => setTimeout(r, delay));
    return callWithRetry(body, attempt + 1);
  }

  if (!res.ok) throw new Error(`MentionsAPI ${res.status}`);
  return res.json();
}

Tips

Cache hits don't count against the sustained rate — repeat queries scale freely.
A single fan-out across four providers is one request (one slot), not four.
Need higher RPS without a plan upgrade? Email [email protected] — we can usually accommodate short-duration burst patterns.