Rate limits

Xpoz applies two limits per account: an instantaneous request rate and a monthly result quota. Both are enforced against the OAuth-authenticated user behind any MCP, SDK, or CLI call.

Per-plan limits

Plan	Requests / min	Concurrent requests	Monthly results	Tracked items
Free	30	2	100,000	1
Pro ($20/mo)	120	6	1,000,000	10
Max ($200/mo)	600	20	10,000,000	30
Enterprise	custom	custom	custom	custom

A "result" is one post, comment, or user record returned by a tool call. Count-only tools (countTweets, checkAccessKeyStatus) do not consume the result quota.

429 contract

When the per-minute rate limit is exceeded, the MCP server returns a JSON-RPC error with code -32099 mapped from a transport-level HTTP 429:

{
  "jsonrpc": "2.0",
  "id": 17,
  "error": {
    "code": -32099,
    "message": "rate_limited",
    "data": {
      "retry_after_ms": 4200,
      "limit": 120,
      "window_seconds": 60
    }
  }
}

Transport headers also carry the contract for non-MCP HTTP probes:

Header	Meaning
`Retry-After`	Seconds to wait before retry (RFC 7231)
`X-RateLimit-Limit`	Requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix seconds at which the window resets

Quota exceeded

When the monthly result quota is exhausted, calls that would return data fail with:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly result quota reached for plan: Free",
    "details": { "plan": "free", "limit": 100000, "reset_at": "2026-06-01T00:00:00Z" }
  }
}

Upgrade at /pricing or wait for the monthly reset. checkAccessKeyStatus returns the live remaining quota.

Retry guidance

429 (rate_limited): sleep for retry_after_ms then retry. For unattended jobs use jittered exponential backoff capped at 60 s.
5xx: retry up to 3 times with exponential backoff (1s, 2s, 4s).
4xx (other): do not retry — the request is malformed or unauthorized.

Avoiding rate limits