Rate limits and safe retries
Rate limit
Gumball limits how many requests one IP address can send each minute. The limit is enforced at the network edge, before a request reaches the API, and it counts API requests and MCP tool calls together.
Past the limit, a request answers 429 with the code rate_limited:
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Wait a minute, then try again.",
"param": null,
"doc_url": null
}
}
This answer comes from the network edge, not the API, so it carries no Request-Id header. Branch on the 429 status, not the body: a 429 isn't guaranteed to carry it.
To stay under the limit:
- Wait before you retry: the number of seconds in the
Retry-Afterheader when the answer has one, and a minute when it doesn't. - Ask for larger pages with
limitinstead of sending more requests. See Pagination. - Don't send requests in parallel that you could send one after another.
Retry a read
Retrying an operation that only reads data is safe. Retry a request that failed with 429, 500, or a network error. Don't retry a 400, 401, 403, or 404 unchanged, because it fails the same way again.
Retry a write
Each operation that changes data accepts an optional Idempotency-Key header, so you can retry without doing the action twice:
- Send a unique value, such as a UUID, with the first attempt.
- Send the same value with each retry of that attempt.
- For 24 hours, a retry with the same key returns the first response instead of acting again.
A tool call through the MCP server carries no Idempotency-Key, so an agent that repeats a tool call repeats the action.
Some operations have a daily cap per account, such as 10 reserves or 20 new campaigns in 24 hours. Past the cap an operation answers 429 with the limit_reached error. The API reference states each operation's cap.
Read this page as plain text.