# 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`: ```json { "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-After` header when the answer has one, and a minute when it doesn't. - Ask for larger pages with `limit` instead of sending more requests. See [Pagination](https://gumball.fm/developers/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](https://gumball.fm/developers/reference) states each operation's cap.