Get startedCLIAPIMCPWebDesktopAgentsSupportBillingChangelog
API · Concepts

Rate limits

Two layers: a generous per-org monthly cap (Free 10k, Pro 100k, Scale 1M API calls) plus per-endpoint burst limits on the few endpoints that can be expensive (search, bulk-import, support, billing).

Monthly cap

  • Free: 10,000 API calls / month
  • Pro: 100,000 / month
  • Scale: 1,000,000 / month

Resets on the calendar UTC month boundary. Hitting the cap returns 402 over_limit (not 429 — it's a billing condition, not a burst condition).

Per-endpoint bursts

EndpointLimitWindow
POST /api/support10per hour per org
POST /api/billing/upgrade5per hour per org
POST /api/billing/downgrade5per hour per org
GET /api/me/export1per hour per user
POST /api/auth (magic link)10per hour per email
POST /api/orgs/:slug/invites20per hour per org

Everything else has no per-endpoint burst limit; the monthly cap is the gate.

Headers we return

X-RateLimit-Monthly-Cap:   100000
X-RateLimit-Monthly-Used:  47281
X-RateLimit-Monthly-Reset: 2026-05-01T00:00:00Z

On bursted endpoints we also return X-RateLimit-Burst-Remaining + X-RateLimit-Burst-Reset.

429 Too Many Requests

{
  "code": "rate_limited",
  "endpoint": "/api/support",
  "limit": 10,
  "window": "hour",
  "resetAt": "2026-04-30T23:00:00Z",
  "message": "Hourly rate limit reached for /api/support."
}

Always includes a Retry-After header (in seconds) per the standard. Waiting is the right move; no exponential backoff needed for these.

402 over_limit (monthly)

Different shape — tied to billing, not to time:

{
  "code": "over_limit",
  "limit": "api_calls",
  "current": 100000,
  "cap": 100000,
  "message": "Monthly API call cap reached. Upgrade to Scale for 1M.",
  "upgrade_url": "https://trydock.ai/pricing"
}

What doesn't count

  • Idempotency replays: re-fetching a cached idempotent response doesn't increment.
  • Webhook delivery requests (we send, you receive): these have their own cap (see Billing → Limits).
  • Failed auth requests (401, 403): hit a separate per-IP throttle, not the API cap.