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.

Frequently asked questions

What are Dock's API rate limits?
Plan-tier-scoped monthly cap on API calls (Free 10K/mo, Pro 100K/mo, Scale 1M/mo) plus per-principal burst limits. Webhook deliveries have a separate cap (Free 1K, Pro 10K, Scale 100K).
What headers does Dock return on rate-limited responses?
`X-RateLimit-Monthly-Cap` (your plan's monthly ceiling), `X-RateLimit-Monthly-Used` (current usage), `X-RateLimit-Monthly-Reset` (unix timestamp of the reset). Same headers on every successful response for at-a-glance budgeting.
What happens when I hit Dock's API rate limit?
429 Too Many Requests for burst limits, 402 Payment Required for monthly cap. The 402 payload includes `details.upgrade` and `details.increase` next-step recommendations so agents can react automatically.
How do I avoid hitting Dock's API rate limit?
Batch where possible (`move_rows` for cross-surface row moves, `append_doc_section` to skip GET-merge-PUT). Subscribe to webhooks instead of polling. Cache `list_workspaces` if it doesn't change often. Use SSE for real-time instead of repeated polls.
Do failed Dock auth requests count against my rate limit?
No. 401s and 403s hit a separate per-IP throttle, not your monthly API cap. Designed so credential-rotation testing or accidental misconfiguration doesn't burn your usage budget.
How do I monitor my Dock API usage in real time?
Three options: read `X-RateLimit-Monthly-*` headers off any response; GET `/api/billing` for the current `apiCallsThisMonth` + cap; Settings → Usage in the dashboard for a chart. All three return the same numbers.
Are MCP calls counted the same as REST calls in Dock's rate limit?
Yes. MCP `tools/call` invocations and equivalent REST endpoints share the org's monthly API call cap. The MCP layer doesn't have a separate budget; same envelope.
Does Dock have per-endpoint rate limits?
Per-principal burst limits (e.g., row writes capped at N/sec per principal) prevent any one agent from monopolizing capacity, but no per-endpoint hard cap. The org's monthly aggregate is the operative ceiling.
Can I get my Dock plan's API cap raised past Scale?
Yes. POST `/api/billing/request-limit-increase` with `{ kind: 'other', desiredValue, reason }`. We register the signal on the admin side; bumps happen when the pattern matches. No tickets, no sales calls.
How long until my Dock API rate limit resets each month?
Resets at the start of your billing period (the day-of-month when you signed up). `X-RateLimit-Monthly-Reset` returns the unix timestamp; convert and you'll see exactly when the counter zeroes out.
Updated