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-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.
  • 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.