Rate limits & quotas

Two independent controls apply to every authenticated call:

1. Rate limit — requests per minute, enforced per key.
2. Quota — calls per month, enforced at the account level (summed across all of the account’s keys), with optional per-key caps as a secondary layer.

Current self-service limits

Plan	Monthly calls	Rate limit	Active API keys
Free	500	10/min	1 key

Free is the only self-service account offer currently available. MCP, paid, and higher-volume limits are provisioned only after direct contact and written confirmation; see Pricing. The keyless sandbox is separate: 5 requests per day per IP.

Rate limit headers

Every rate-limited response (success or failure) carries:

Header	Meaning
X-RateLimit-Limit	Requests allowed per minute for this key
X-RateLimit-Remaining	Requests left in the current window
X-RateLimit-Reset	Unix timestamp (seconds) when the window resets
Retry-After	Seconds to wait — sent on 429 only

When you exceed the rate limit

429 with this body:

{
  "error": "Rate limit exceeded",
  "retryAfter": 31,
  "limit": 10,
  "windowMs": 60000
}

Back off for retryAfter seconds (or until X-RateLimit-Reset), then retry. The window is a fixed 60 seconds from the first request in the window.

When you exceed a quota

Quotas are checked before the request runs, account level first. 429 with this body:

{
  "error": "monthly quota exceeded",
  "quota": "monthly",
  "scope": "account",
  "limit": 500,
  "used": 500
}

• quota is "daily" or "monthly".
• scope is "account" (usage summed across all the account’s keys) or "api_key" (a per-key cap).
• Quotas count successful calls only — errors don’t consume quota.
• Monthly quotas reset at the start of the calendar month (UTC); daily quotas at midnight UTC.

There is no overage billing on Free: at the limit you get 429s until the period resets or StockAlloy confirms a different written limit. See Pricing for contact details.

Telling the two 429s apart

Both come back as HTTP 429. Rate-limit bodies have retryAfter and windowMs; quota bodies have quota, scope, and used. A rate-limit 429 resolves in under a minute; a quota 429 needs a new period or a directly arranged limit change.

Sandbox limit

The keyless sandbox returns 429 with error code SANDBOX_LIMIT once your IP has used its 5 daily requests. Watch the X-Sandbox-Remaining header.

Client guidance

• Respect Retry-After; use exponential backoff with jitter for 5xx.
• Watch X-RateLimit-Remaining and pre-emptively smooth bursts.
• Facts responses are per-company exports — cache them on your side rather than re-fetching per user interaction. Filings are immutable; a fact row only changes when a new filing supersedes it.