# Rate Limits

Source: https://coolify.io/docs/api/rate-limits

Coolify limits API request frequency to protect the instance from excessive traffic. Clients should read the rate-limit response headers instead of assuming that every instance uses the default.

## Default limits

| Requests             | Default limit  | Window   |
| :------------------- | :------------- | :------- |
| General API requests | 200 requests   | 1 minute |
| `/api/health`        | 1,000 requests | 1 minute |

Coolify Cloud uses these default limits. Self-hosted instances use the same defaults unless an administrator changes the general limit with `API_RATE_LIMIT`. The health endpoint keeps its separate 1,000-request limit.

Coolify identifies a rate-limit bucket by the authenticated user when one is available. Requests without an authenticated user are grouped by source IP address.

***

## Failed request limit

Coolify also limits API clients that keep failing. By default, a client can send 30 failed requests per minute. Coolify counts these responses:

* `401 Unauthenticated` and `403 Forbidden`
* `404 Not Found` for a request without a Bearer token

Each API token has its own count. Requests without a token are counted by source IP address. The `/api/health` and `/api/v1/health` endpoints are not counted. The limit applies only to REST API requests under `/api/`. Requests to the MCP endpoint `/mcp` are not counted or blocked.

When a client reaches the limit, Coolify answers all its requests with `429 Too Many Requests` and a `Retry-After` header:

```json
{
  "message": "Too many failed API requests. Retry after 60 seconds."
}
```

The first block lasts 1 minute. If the client reaches the limit again within one hour, the block lasts 5 minutes and then 15 minutes.

When a token reaches the limit, the team of the token receives a notification on each enabled notification channel, at most once a day for each token. Find the client that uses the token and fix its requests, give the token the permissions it needs, or revoke it.

***

## Rate-limit headers

API responses include headers that describe the current request bucket:

| Header                  | When present            | Meaning                                                             |
| :---------------------- | :---------------------- | :------------------------------------------------------------------ |
| `X-RateLimit-Limit`     | API responses           | Maximum requests allowed in the current window.                     |
| `X-RateLimit-Remaining` | API responses           | Requests remaining in the current window after the current request. |
| `Retry-After`           | A rate-limited response | Seconds to wait before trying again.                                |
| `X-RateLimit-Reset`     | A rate-limited response | Unix timestamp in seconds when another request can be attempted.    |

Inspect the headers without downloading the response body:

```sh
export COOLIFY_URL="https://coolify.shadowarcanist.com"
export COOLIFY_TOKEN="67|abcthisisa123dummytoken"

curl --head \
  --header "Authorization: Bearer $COOLIFY_TOKEN" \
  "$COOLIFY_URL/api/v1/team"
```

Some endpoints can also return `429 Too Many Requests` because a deployment queue or an upstream cloud provider is busy. Use `Retry-After` whenever the response provides it, even when `X-RateLimit-Remaining` shows capacity in Coolify's general API limit.

***

## Handle a 429 response

When Coolify returns `429 Too Many Requests`:

1. Stop sending requests for the affected operation.
2. Read `Retry-After` as a number of seconds.
3. Wait for that interval before retrying.
4. Add exponential backoff and random jitter if repeated attempts still fail.
5. Avoid retrying unsafe write requests unless the endpoint and client can prevent duplicate changes.

A `429` with the message `Too many failed API requests` means that the client reached the [failed request limit](https://coolify.io/docs/api/rate-limits#failed-request-limit). Fix the cause of the `401`, `403`, or `404` responses before you retry.

Do not send parallel retries for the same failed request. Parallel retries consume the remaining capacity faster and can repeat a write operation.

***

## Change the instance-wide rate limit

**Self-hosted**

Set `API_RATE_LIMIT` in `/data/coolify/source/.env` to change the number of general API requests allowed per minute. Set `API_FAILED_REQUEST_RATE_LIMIT` to change the number of failed requests allowed per minute; `0` turns off the failed request limit:

```dotenv
API_RATE_LIMIT=400
API_FAILED_REQUEST_RATE_LIMIT=30
```

The running container does not pick up this change from a normal restart. Run the Coolify installation script to recreate the Coolify containers with the updated environment:

```sh
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
```

The installation script also updates Coolify to the latest release. Follow [Update Coolify](https://coolify.io/docs/core/instance-management/update#manual-update-via-terminal) if you need to install a specific version.

After the containers are recreated, make a request and confirm that `X-RateLimit-Limit` reports the new general limit.

Increasing this value does not increase the capacity of the Coolify instance, deployment queues, or upstream providers. Prefer client-side caching, request batching, and backoff before raising it.

**Coolify Cloud**

Coolify Cloud users cannot change the instance environment. To request a higher limit, [contact Coolify support](https://coolify.io/docs/support) and explain why the integration needs more than 200 general API requests per minute. Include the endpoints being called and the expected sustained and peak request rates so the request can be evaluated.

See [API errors](https://coolify.io/docs/api/errors) for the difference between a general rate-limit response and other API failures.