Rate Limits

The Fizzy MCP hosted service implements rate limiting to ensure fair usage and maintain service quality for all users. This page explains how rate limits work, what tiers are available, and how to monitor your usage.

Overview

Rate limits are applied on a per-token basis, meaning each unique Fizzy Personal Access Token has its own rate limit counters. Limits reset daily at midnight UTC.

Rate Limit Tiers

The hosted service has three rate limit tiers:

Anonymous

100 writes/day 1,000 reads/day Default tier when using only a Fizzy token without an API key.

Authenticated

1,000 writes/day 10,000 reads/day 10x higher limits when using an API key.

Admin

Unlimited Unlimited Reserved for internal use and special accounts.

Tier Comparison

Tier	Writes/Day	Reads/Day	How to Get
Anonymous	100	1,000	Default (Fizzy token only)
Authenticated	1,000	10,000	Add `X-API-Key` header
Admin	Unlimited	Unlimited	Internal/special accounts

What Counts as a Write vs Read?

Understanding what operations count as writes versus reads helps you manage your rate limits effectively.

Write Operations

Write operations modify data in Fizzy. Each write operation counts as 1 write against your daily limit.

Tool	Operation
`fizzy_create_card`	Create a new card
`fizzy_update_card`	Update card title, description, or tags
`fizzy_delete_card`	Delete a card
`fizzy_close_card`	Mark a card as complete
`fizzy_reopen_card`	Reopen a closed card
`fizzy_postpone_card`	Move card to Not Now
`fizzy_triage_card`	Move card to a column
`fizzy_untriage_card`	Remove card from column
`fizzy_tag_card`	Toggle a tag on a card
`fizzy_assign_card`	Assign/unassign a user
`fizzy_watch_card`	Subscribe to notifications
`fizzy_unwatch_card`	Unsubscribe from notifications
`fizzy_pin_card`	Pin a card
`fizzy_unpin_card`	Unpin a card
`fizzy_mark_golden`	Mark card as important
`fizzy_unmark_golden`	Remove golden status
`fizzy_create_board`	Create a new board
`fizzy_update_board`	Update board settings
`fizzy_delete_board`	Delete a board
`fizzy_publish_board`	Make board public
`fizzy_unpublish_board`	Make board private
`fizzy_create_column`	Create a new column
`fizzy_update_column`	Update column settings
`fizzy_delete_column`	Delete a column
`fizzy_create_comment`	Add a comment
`fizzy_update_comment`	Edit a comment
`fizzy_delete_comment`	Delete a comment

Read Operations

Read operations retrieve data from Fizzy without modifying it. Each read operation counts as 1 read against your daily limit.

Tool	Operation
`fizzy_get_identity`	Get current user info
`fizzy_get_account`	Get account settings
`fizzy_list_boards`	List all boards
`fizzy_get_board`	Get board details
`fizzy_list_cards`	List/search cards
`fizzy_get_card`	Get card details
`fizzy_list_columns`	List columns on a board
`fizzy_get_column`	Get column details
`fizzy_list_comments`	List comments on a card
`fizzy_get_comment`	Get comment details
`fizzy_list_tags`	List all tags
`fizzy_list_users`	List account users
`fizzy_get_user`	Get user details

Special Cases

Rate Limit Headers

Every response from the hosted service includes headers that tell you your current rate limit status. Use these to monitor your usage and avoid hitting limits.

Response Headers

Header	Description	Example
`X-RateLimit-Limit`	Maximum requests for this operation type	`100`
`X-RateLimit-Remaining`	Requests remaining until reset	`73`
`X-RateLimit-Reset`	UTC datetime when limits reset	`2024-01-16T00:00:00Z`
`X-User-Tier`	Your current rate limit tier	`authenticated`

Example Response Headers

HTTP/2 200 OK
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 2024-01-16T00:00:00Z
X-User-Tier: authenticated

This example shows:

User has 1,000 writes/day limit (authenticated tier)
847 writes remaining until reset
Limits reset at midnight UTC on January 16, 2024
User is on the authenticated tier

Checking Your Limits with curl

curl -I -X POST https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -H "X-Fizzy-Token: fz_your_token_here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The -I flag shows only headers, and tools/list doesn’t count against limits, so this is a free way to check your status.

Daily Reset

Rate limits reset daily at midnight UTC (00:00:00 UTC).

Reset Times by Timezone

Timezone	Reset Time
UTC	00:00 (midnight)
US Pacific (PST)	16:00 (4 PM previous day)
US Eastern (EST)	19:00 (7 PM previous day)
UK (GMT)	00:00 (midnight)
Central Europe (CET)	01:00 (1 AM)
Japan (JST)	09:00 (9 AM)
Australia (AEST)	10:00 (10 AM)

What Happens When Limits Are Exceeded

When you exceed your rate limit, the hosted service returns a 429 Too Many Requests response.

429 Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Rate limit exceeded. Limit: 100 writes/day. Resets at: 2024-01-16T00:00:00Z",
    "data": {
      "type": "write",
      "limit": 100,
      "remaining": 0,
      "reset": "2024-01-16T00:00:00Z",
      "tier": "anonymous"
    }
  }
}

429 Response Headers

HTTP/2 429 Too Many Requests
Content-Type: application/json
Retry-After: 3600
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2024-01-16T00:00:00Z
X-User-Tier: anonymous

The Retry-After header indicates how many seconds to wait before retrying.

Handling 429 Responses

Check the Retry-After header to know when you can retry
Check the X-RateLimit-Reset header to know when limits fully reset
Consider upgrading to the authenticated tier for 10x more requests
Batch operations where possible to reduce total request count
Cache read results locally when data doesn’t change frequently

Tips for Staying Within Limits

For Anonymous Tier (100 writes, 1,000 reads)

Optimize Reads
Optimize Writes

Cache board and card lists locally - Use fizzy_list_cards with filters instead of fetching all cards - Avoid repeatedly fetching the same card details - Use fizzy_get_board once to get board metadata

For Authenticated Tier (1,000 writes, 10,000 reads)

The authenticated tier provides 10x more capacity, which is sufficient for most professional workflows:

1,000 writes/day = ~40 writes/hour over a 24-hour period
10,000 reads/day = ~400 reads/hour

This is typically enough for:

Creating 50-100 cards per day
Heavy searching and filtering
Automation workflows with multiple AI agents
Team collaboration scenarios

Monitoring Your Usage

In Your AI Agent

Most AI agents will show rate limit errors when they occur. You can also ask your AI assistant:

“What are my current Fizzy rate limits?”

The response will include information from the rate limit headers.

Programmatically

Build monitoring into your integration:

async function callFizzy(method: string, params: any) {
  const response = await fetch('https://fizzy-mcp-hosted.ryanyogan.workers.dev/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Fizzy-Token': process.env.FIZZY_TOKEN,
      'X-API-Key': process.env.FIZZY_API_KEY,
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method,
      params,
    }),
  });

  // Log rate limit status
  console.log({
    limit: response.headers.get('X-RateLimit-Limit'),
    remaining: response.headers.get('X-RateLimit-Remaining'),
    reset: response.headers.get('X-RateLimit-Reset'),
    tier: response.headers.get('X-User-Tier'),
  });

  return response.json();
}

Frequently Asked Questions

Can I request higher limits?

For most users, the Authenticated tier (1,000 writes/day) is sufficient. If you have specific needs that exceed this, contact us to discuss options.

Do rate limits apply to all accounts?

Yes, rate limits are per-token, so each Fizzy account (token) has its own limits. Using multiple tokens would give you separate limits, but this should align with having legitimate separate Fizzy accounts.

What if I need unlimited access?

Run Fizzy MCP locally with npx @fizzy-mcp/server. Local mode has no rate limits.

Are rate limits shared across tools?

Reads and writes have separate limits. Using all your reads doesn’t affect your write limit, and vice versa.

Do failed requests count against limits?

No. Only successful requests (2xx responses) count against your rate limits. Validation errors (4xx) and server errors (5xx) do not consume your quota.

Next Steps

API Keys - Get an API key for 10x higher rate limits
Hosted Service Overview - Learn more about the hosted architecture
Local Mode - Run locally for unlimited access