Agent Rate Limits¶

!!! info "TL;DR" Rate limits are enforced per agent via Upstash Redis. Three tiers: Standard (60/min), Professional (300/min), Enterprise (1000/min). Custom limits available via policies.

Rate Limit Tiers¶

Each agent is assigned a rate limit tier. The tier determines requests per minute across all MCP tools.

Rate limits are tracked per agent, not per API key. If an agent has multiple keys, the limit applies to all keys combined.

How Rate Limiting Works¶

The MCP server uses Upstash Redis with a sliding window algorithm. Each request:

1. Increments a counter in Redis with the agent's ID
2. Sets a TTL of 60 seconds
3. Checks the current count
4. If count exceeds limit, returns 429 Too Many Requests
5. If within limit, proceeds to execution

Rate Limit Headers¶

Every response includes rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1675123456

• X-RateLimit-Limit — Total requests allowed per minute
• X-RateLimit-Remaining — Requests remaining in current window
• X-RateLimit-Reset — Unix timestamp when the window resets

Rate Limit Response¶

If rate limited, the server returns:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "data": {
      "limit": 60,
      "window": "1 minute",
      "retry_after": 42
    }
  }
}

The retry_after field indicates seconds until the window resets.

Custom Rate Limits¶

You can override the default tier limit with a custom policy. In the admin dashboard:

1. Navigate to Settings → Agents → Policies
2. Create or edit a policy
3. Under Rate Limiting, set custom limits
4. Assign the policy to the agent

Example: Custom Policy¶

{
  "name": "high-volume-survey-agent",
  "scopes": ["surveys:*", "responses:*"],
  "rate_limit": {
    "requests_per_minute": 500,
    "burst": 50
  }
}

The burst parameter allows short spikes above the sustained rate. If the agent sends 50 requests in 5 seconds, it won't be rate limited, but sustained load above 500/min will trigger limiting.

Per-Tool Rate Limits¶

Some tools have additional rate limits beyond the agent-level limit:

These limits apply even if the agent hasn't hit its overall rate limit.

Rate Limit Monitoring¶

The admin dashboard shows real-time rate limit usage under Settings → Agents → [Agent Name] → Activity.

Metrics include:

• Current requests/minute
• Peak requests/minute (last 24h)
• Total requests (last 7 days)
• Rate limit violations (last 7 days)

You can set up alerts to notify when an agent consistently hits its rate limit. This might indicate:

• The agent needs a higher tier
• A bug is causing excessive requests
• Malicious activity

Best Practices¶

1. Cache responses — Don't re-fetch data you already have
2. Batch operations — Use bulk tools when available (e.g., list_surveys instead of multiple get_survey calls)
3. Implement backoff — If rate limited, wait before retrying
4. Use webhooks — Subscribe to realtime events instead of polling
5. Monitor usage — Set up alerts for approaching limits

Example: Backoff Logic¶

async function callMcpTool(tool: string, params: unknown, retries = 3) {
  try {
    return await mcpClient.call(tool, params)
  } catch (error) {
    if (error.code === 429 && retries > 0) {
      const retryAfter = error.data.retry_after || 60
      await sleep(retryAfter * 1000)
      return callMcpTool(tool, params, retries - 1)
    }
    throw error
  }
}

Upgrading Tiers¶

To upgrade an agent's rate limit tier:

1. Navigate to Settings → Agents → [Agent Name]
2. Click Change Tier
3. Select new tier
4. Click Save

Changes take effect immediately. No API key regeneration required.

For custom tiers above 1000 requests/minute, contact support at support@canviq.app.

What's Next¶

• Authentication — API keys and scopes
• MCP Server — How rate limiting is implemented
• Available Tools — Which tools have additional limits