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

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:

{
  "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:

Inspect the headers without downloading the response body:

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

API_RATE_LIMIT=400
API_FAILED_REQUEST_RATE_LIMIT=30

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

See API errors for the difference between a general rate-limit response and other API failures.