Get started

Rate limits

Each API key, each workspace and each installed app has a request budget that refills every second, and a daily quota by plan. When one runs out, the API answers 429 and tells you how long to wait.

Limits per plan

Limits are token buckets: a key can send a burst of requests at once, and the budget refills at a steady rate per second. Every request with an API key counts against both the key's bucket and the workspace's bucket, which all keys of the workspace share.

• New workspaces (trust level 0) refill at half these rates until Kweko trusts them; the burst stays the same.
• Parallel requests. One key may have at most 10 requests in flight. The eleventh answers concurrency_limited.
• Apps have their own buckets, see below.
• People using Kweko in the browser have their own budget, which integrations never share.

Daily quota

On top of the per-second buckets, the API keys of a workspace share a daily request quota by plan:

The day is the UTC day: quotas reset at 00:00 UTC (05:00 in Tashkent). Refused requests don't count. Past the quota the API answers rate_limited with reason: "api_requests_day", the plan, limit and used, and Retry-After in seconds until the reset. Settings → Usage & limits shows today's count; Kweko support can raise the quota for a workspace.

Apps

Each installed app (OAuth tokens and calls from its frames) has its own limits, apart from the workspace's API keys, so a busy app cannot slow down the workspace's integrations and the integrations cannot slow down an app:

• a bucket per installation, the size of one API key's bucket on the workspace's plan;
• at most 10 requests in flight per installation (concurrency_limited, reason: "app_concurrency");
• a daily quota per installation the size of the workspace's daily quota (reason: "app_requests_day").

Headers

Requests made with an API key carry the state of the key's bucket (an app's requests: its installation's bucket) and of the daily quota:

The names follow the IETF RateLimit header fields draft, without an X- prefix.

When you hit a limit

The API answers 429 Too Many Requests with a Retry-After header in seconds and one of two codes:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please slow down.",
    "request_id": "req_4f2a9c1e0b7d3a55",
    "docs_url": "https://developers.kweko.uz/errors/rate_limited",
    "reason": "api_key_rate",
    "limit": 50
  }
}

reason says which limit it was: api_key_rate (this key's bucket), workspace_api_rate (the workspace's shared bucket), api_requests_day (the daily quota), app_rate or app_requests_day (an app's own limits). With concurrency_limited it is api_key_concurrency or app_concurrency.

To stay under the limits:

1. Wait at least Retry-After seconds before retrying, and add exponential backoff with jitter if it happens again.
2. Keep an eye on RateLimit-Remaining and slow down before it reaches 0.
3. Use webhooks instead of polling for changes.
4. Page with limit=250 to fetch lists in fewer requests.
5. Keep parallel requests per key at 10 or fewer.

Other limits

• Request bodies: 1 MB.
• Endpoints you call without a key (sign-in, OAuth token, payment and messenger callbacks, download links) are limited per IP address; a flood gets rate_limited with reason: "ip_rate". Normal use never reaches it.
• Per workspace, whatever the plan: 50 invites a day and 200 waiting at once, 20 exports an hour and 3 running at once, 2 imports running at once, 20 imports a day. These answer rate_limited or too_many_jobs with a reason.
• Plan limits on how many records of a kind a workspace can have (members, pipelines, custom fields, automations, webhooks, API keys, installed apps, storage, rows per import) answer 403 limit_reached with key, limit, used, plan and upgrade_to, see kweko.uz/pricing. GET /v1/usage (scope workspace:read) lists every limit with its usage.
• A workspace whose subscription is unpaid becomes read-only: writes answer 402 read_only until it is paid.