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_assetcounts 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 a429 response with a Retry-After header indicating how many seconds to wait:
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 a429 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-Remainingto proactively throttle requests before hitting limits - Batch operations when possible to reduce total token consumption
- Cache responses to avoid redundant requests