Rate limits

FlowKoi enforces three independent caps. Each can be tuned (the per-key and per-project ones) or is hard-capped for plan reasons (monthly quota).

1. Per-key request rate

Token bucket, refilled linearly:

• Default — 60 requests per minute per API key.
• Adjustable — set rateLimitRpm in Project Settings → API → key → edit. Range: 1–10 000.

Every response carries:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1717263012

X-RateLimit-Reset is the epoch seconds when the bucket will refill — use it to schedule your next call. Over-limit requests get:

HTTP/1.1 429 Too Many Requests
Retry-After: 9
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded (60 req/min). Retry in 9s."
  }
}

Each key gets its own bucket — minting more keys is the simplest way to fan out a write-heavy workload without touching the cap.

2. Concurrent runs per project

Default 10 concurrent running instances per project. Adjust via Project Settings → Quotas → max concurrent runs.

Over-cap trigger calls get:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": {
    "code": "CONCURRENT_LIMIT",
    "message": "Project has 10 active runs (cap 10). Stop or wait for one to finish.",
    "limit": 10,
    "current": 10
  }
}

This cap is checked before spawning any container, so over-cap calls never spend money. Stop a finishing run with POST /runs/{runId}/stop to free a slot.

3. Monthly run quota

Default unlimited (null). Set a hard ceiling per project — useful for budget control on a shared key — via Project Settings → Quotas → monthly run quota.

The counter resets on the 1st of each calendar month, UTC. Over-quota calls get:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": {
    "code": "MONTHLY_QUOTA",
    "message": "Project has used 5000/5000 API runs this month.",
    "limit": 5000,
    "current": 5000
  }
}

Only API-triggered runs (triggerType: "api") count — manual triggers from the dashboard and scheduled cron runs are excluded.

Order of checks

When you POST /flows/{flowId}/runs, the gates fire in this order:

1. API key valid & not revoked.
2. Rate limit (per-key token bucket) — RATE_LIMITED.
3. Concurrent cap — CONCURRENT_LIMIT.
4. Monthly quota — MONTHLY_QUOTA.
5. Container spawn.

Steps 1–4 are cheap. Step 5 is what costs money — so the gates exist to never reach it unnecessarily.

What to do when you get throttled