# Quotas & Limits

This page explains how rate limiting and quota enforcement work for the Safe Infrastructure API.

For authentication setup instructions and usage examples, see [API Keys & Authentication](./how-to-use-api-keys.mdx).

## Plans and limits

One **API unit** equals **1 HTTP request** to any Safe Infrastructure endpoint.

See [Safe API plans](https://safe.global/api#plans) for the limits of each plan. To subscribe or upgrade, log in to the [developer dashboard](https://developer.safe.global/api-subscriptions).

## Response headers

The API returns these headers. The **Present** column says when each one is sent.

| Header | Present | Meaning |
| --- | --- | --- |
| `X-RateLimit-Limit` | Always | Monthly quota of your plan, or the unauthenticated quota without an API key. |
| `X-RateLimit-Remaining` | Always | Requests left in the current window. |
| `X-RateLimit-Reset` | Always | Seconds until the window resets. Not a timestamp. |
| `X-Consumer-Id` | With an API key | Your account identifier. |
| `X-Consumer-RPS` | With an API key | Requests per second allowed for your account. |
| `X-RateLimit-Plan` | With an API key | Your plan: `builder`, `growth` or `scale`. |
| `X-RateLimit-Warning` | From 80% of the quota | `<N>% of monthly quota used. Plans: https://safe.global/api#plans`. |

Example response:

```
HTTP/1.1 200 OK
X-RateLimit-Limit: 50000
X-RateLimit-Remaining: 9500
X-RateLimit-Reset: 1209600
X-Consumer-Id: 1a2b3c4d
X-Consumer-RPS: 5
X-RateLimit-Plan: builder
X-RateLimit-Warning: 81% of monthly quota used. Plans: https://safe.global/api#plans
```


## Quota window

The monthly quota is a **30-day window** that starts at your account's first request, not a calendar month or billing date. Changing your plan starts a new window.

Enforcement is applied at the **account level**, not per API key:

- All API keys under an account share the same quota and requests-per-second allowance.
- Creating multiple API keys does not increase your limits.

<Callout type="warning">
  **Anti-circumvention:** Creating multiple accounts to circumvent rate limits or quotas violates the Safe Infrastructure terms of service. Accounts engaging in this behavior may be suspended.
</Callout>

## 429 responses

When a limit is reached, the API returns **HTTP 429 Too Many Requests**. The body is always `{"error_msg": "..."}`. This field name is kept for existing clients.

### Monthly quota reached

Returned once the account has used its monthly quota. The message names your plan, the reset date and how to upgrade.

Builder:

```json
{
  "error_msg": "The monthly quota of 50000 requests on the Builder plan is used. It resets on 15 Nov 2026. Upgrade to the Growth plan at https://developer.safe.global/api-subscriptions, or please book a call on <booking-link>."
}
```

Growth:

```json
{
  "error_msg": "The monthly quota of 1000000 requests on the Growth plan is used. It resets on 15 Nov 2026. Upgrade to the Scale plan at https://developer.safe.global/api-subscriptions, or please book a call on <booking-link>."
}
```

Scale:

```json
{
  "error_msg": "The monthly quota of 3000000 requests on the Scale plan is used. It resets on 15 Nov 2026. For a higher limit, please book a call on <booking-link>."
}
```

### Per-second limit reached

Returned when the account sends more requests per second than its plan allows.

```json
{
  "error_msg": "This account is limited to 5 requests per second on the Builder plan. Retry after 1 second."
}
```

### Without an API key

Returned when an unauthenticated request exceeds the unauthenticated limits.

Per second:

```json
{
  "error_msg": "Too many requests per second"
}
```

Monthly quota:

```json
{
  "error_msg": "Too many requests in time window"
}
```


## Handling 429 responses

- **Rejected requests still count** against your quota. Retrying in a tight loop only burns it faster.
- **Monthly quota 429:** stop sending requests until `X-RateLimit-Reset` seconds have passed, or [upgrade your plan](https://developer.safe.global/api-subscriptions).
- **Per-second 429:** retry after one second.
- **Before you hit 429:** watch `X-RateLimit-Warning`. It appears from 80% of your quota, which leaves time to upgrade without an outage.
