Rate limits
FlushKit enforces two kinds of limits: per-plan monthly event quotas and per-second request rate limits.
Monthly event quota
Every plan includes a monthly allowance of notification events (one event = one POST /v1/notify call, regardless of how many devices receive it).
| Plan | Events / month |
|---|---|
| Free | 1,000 |
| Starter | 50,000 |
| Growth | 500,000 |
The quota resets at the start of each billing period. You can monitor usage in real time from the Overview tab of your project dashboard.
What happens when you hit the quota
POST /v1/notify returns 429 Too Many Requests with:
{
"code": "EVENT_LIMIT_REACHED",
"limit": 1000,
"used": 1000
}
Existing SSE connections remain open — connected devices stay listening. Only new notify calls are rejected.
Request rate limit
The API enforces a burst limit of 60 requests per minute per API key across all endpoints. This is a sliding-window limit.
If you exceed it, the API returns 429 Too Many Requests with:
{ "code": "RATE_LIMIT_EXCEEDED", "retryAfterSeconds": 12 }
Use the retryAfterSeconds value to schedule a retry:
async function notifyWithRetry(payload: object, attempts = 3) {
for (let i = 0; i < attempts; i++) {
const res = await fetch('https://api.flushkit.dev/v1/notify', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.FLUSHKIT_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
})
if (res.status === 429) {
const body = await res.json()
if (body.code === 'RATE_LIMIT_EXCEEDED') {
const wait = (body.retryAfterSeconds ?? 10) * 1000
await new Promise((r) => setTimeout(r, wait))
continue
}
}
return res
}
throw new Error('Exceeded retry limit')
}
Checking your usage
You can inspect current usage programmatically via GET /v1/projects/me:
curl https://api.flushkit.dev/v1/projects/me \
-H "Authorization: Bearer fk_live_••••••••••••••••"
The response includes usage.eventsThisPeriod and usage.eventLimit for each project.
FlushKit sends an email notification when your project reaches 80% and 100% of its monthly quota so you can upgrade before hitting the limit.