Skip to main content
REST API requests are rate limited using a weighted token bucket to ensure fair usage and platform stability.

How It Works

Each user has a token bucket with a fixed capacity that refills at a steady rate. Every API request consumes tokens based on its cost — heavier operations like uploads consume more tokens than simple reads.

Request Costs

Different operations consume different amounts of tokens:

MCP Tool Calls

If you use the MCP server, tool calls follow the same weighted cost model as the REST API. Each tool call is charged once using the cost of the closest REST operation. For example:
  • Search and list tools use the list/search cost
  • Write tools use the corresponding mutation cost
  • view_asset counts like a metadata read rather than a full file download

Rate Limit Headers

Rate limit information is included in every response:

Handling Rate Limits

When rate limited, you’ll receive a 429 response with a Retry-After header indicating how many seconds to wait:
Respect the Retry-After value before retrying:
If you’re using one of our SDKs, automatic retries with exponential backoff are built in.

Concurrent Requests

Separately from the token bucket, Gumnut limits how many of your requests it processes at the same time. Requests over that limit wait their turn, so a burst is slowed rather than rejected. If too many of your requests are already waiting, new ones receive a 429 with a Retry-After header and the body {"detail": "Too many concurrent requests"}. Handle it like any other 429: wait for Retry-After, then retry. Sending fewer requests in parallel avoids it.

Best Practices

  • Monitor X-RateLimit-Remaining to proactively throttle requests before hitting limits
  • Batch operations when possible to reduce total token consumption
  • Cache responses to avoid redundant requests