> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breakcold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> Understand REST API rate limits and what to do when you hit one.

Rate limits protect Breakcold and your workspace from too many requests at once. They also help keep automations predictable when several tools are connected to the same account.

Most users never need to think about rate limits. You only need this guide if an integration, script, or automation starts receiving `429 Too Many Requests`.

## Token costs

REST API routes use fixed token pricing. Most read routes cost 20 tokens per successful request. Write routes cost 40 tokens per successful request.

`GET /workspaces` is free. MCP route-backed tool calls use the same token pricing as the matching REST API route. MCP utility tools are free.

## How limits work

Breakcold checks several limits at the same time. A request is blocked when any one of those limits is full.

| Limit                        | Current budget                                                      |
| ---------------------------- | ------------------------------------------------------------------- |
| Organization                 | 600 requests per minute                                             |
| Workspace                    | 300 requests per minute                                             |
| User, app, or agent identity | 180 requests per minute                                             |
| API key                      | 180 requests per minute when an API key is used                     |
| Route                        | 120 requests per minute for the same route in the same organization |

The limit that matters is the first one you reach. For example, a script can be under the organization limit but still hit the API key limit if it sends too many requests with the same key.

## What happens when you hit a limit

The REST API returns `429 Too Many Requests`.

When possible, the response includes a `Retry-After` header in seconds and a `retryAfterMs` value in the JSON body.

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Public API rate limit exceeded",
    "requestId": "request_id",
    "retryAfterMs": 12000
  }
}
```

## What your integration should do

When you receive `429`, wait before trying again. If the response includes `Retry-After`, wait at least that long.

Good retry behavior:

* Wait before retrying.
* Retry a small number of times.
* Add a longer delay after each failed retry.
* Avoid sending many retries in parallel.

Avoid immediate retry loops. They usually make the limit last longer.

## How to avoid rate limits

* Reuse data you already fetched instead of polling the same endpoint repeatedly.
* Use pagination instead of asking for very large lists at once.
* Queue write actions so they run steadily instead of all at the same second.
* Use the narrowest workspace access needed for each key.
* Split unrelated automations across separate keys only when they are truly separate workflows.

If your integration regularly needs more volume, contact Breakcold support with the route, request volume, workspace, and `requestId` values from the rate-limited responses.