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.
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:
export COOLIFY_URL="https://coolify.shadowarcanist.com"
export COOLIFY_TOKEN="67|abcthisisa123dummytoken"
curl --head \
--header "Authorization: Bearer $COOLIFY_TOKEN" \
"$COOLIFY_URL/api/v1/teams/current"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:
- Stop sending requests for the affected operation.
- Read
Retry-Afteras a number of seconds. - Wait for that interval before retrying.
- Add exponential backoff and random jitter if repeated attempts still fail.
- Avoid retrying unsafe write requests unless the endpoint and client can prevent duplicate changes.
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
Set API_RATE_LIMIT in /data/coolify/source/.env to change the number of general API requests allowed per minute:
API_RATE_LIMIT=400The 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:
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bashThe installation script also updates Coolify to the latest release. Follow Update Coolify 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 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.
See API errors for the difference between a general rate-limit response and other API failures.