Agent Rate Limits¶

!!! info "TL;DR" Rate limits are enforced per agent via Upstash Redis. Three tiers: Standard (30/min), Growth (300/min), Scale (1000/min).

Rate Limit Tiers¶

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

The Standard tier is read-only; write access starts at Growth. 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: 30
X-RateLimit-Remaining: 15
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 429 Too Many Requests with an RFC 7807 Problem Details body, the same error shape used by every other MCP error:

{
  "type": "https://canviq.app/errors/rate-limited",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Too many requests. Retry after 42 seconds.",
  "request_id": "mcp_2b1a9c7e-0f3d-4a8e-9b21-6e2c4d8f1a30"
}

The response also sets a Retry-After header (in seconds) indicating when the window resets. See the MCP Tools API reference for the full error contract.

Changing an Agent's Tier¶

Each agent's limit comes from one of the three preset tiers above. There is no self-serve control for an arbitrary per-agent numeric limit or a burst allowance today: the limiter maps a tier to a fixed window (30, 300, or 1000 requests per minute) and nothing else. To move an agent to a higher tier, contact support at support@canviq.app.

Per-Tool Rate Limits¶

One tool carries an additional limit beyond the agent-level tier:

This limit applies even if the agent hasn't hit its overall tier 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 list tools when available (e.g., a single survey_list call instead of many survey_list calls with an id filter)
3. Implement backoff — If rate limited, wait before retrying
4. Avoid tight polling loops: There is no push notification mechanism for MCP agents today; space out repeated survey_list / response_list calls rather than polling in a hot loop
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 move an agent to a higher tier, contact support at support@canviq.app. Tier changes take effect without any API key regeneration. There is no self-serve tier switcher or numeric limit above 1000 requests/minute today.

What's Next¶

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