Rate limits and caps
Four separate ceilings, for four separate reasons. Two protect the API, two protect your money — and the ones protecting your money are yours to set.
Requests per minute
Every account has a sustained per-minute request limit and a shorter burst limit over a 10-second window. The burst limit exists so that a minute's entire quota cannot be spent in the first 200 milliseconds; the per-minute limit exists so that steady traffic is still possible. New accounts start at 120 requests per minute. Ask if your workload needs more — this one is a dial, not a policy.
Every response carries where you stand:
x-ratelimit-limit: 120
x-ratelimit-remaining: 118
x-ratelimit-reset: 1785840120Go over and you get 429 rate_limit_exceeded with a Retry-After header in seconds. Wait that long and retry — the window is fixed, so waiting works; retrying immediately does not.
Calls at the same time
This is the ceiling that protects real capacity rather than a counter, which is why it is sized to your account rather than published as one number. When you are at your limit, the next call is not queued and not rejected as an error — it is simply not started yet, and the next attempt starts it.
You can also cap a single customer below your account ceiling with max_concurrent_calls on PATCH /v1/customers/{id}/limits. That never raises your account ceiling; it only stops one customer from consuming all of it.
Spend caps
Two levels, and they stack. Your account caps — daily and monthly — are set by your Kleos contact and stop every call once reached. Your per-customer caps are yours, set through the API:
curl -X PATCH https://api.kleos.click/v1/customers/crm-8842/limits \
-H "Authorization: Bearer kls_live_..." \
-H "Content-Type: application/json" \
-d '{"daily_spend_cap_cents":2000,"monthly_spend_cap_cents":40000}'Send null to clear a cap; omit a field to leave it alone. The pool is shared, so this is the lever that stops one customer's unattended campaign from spending money that is funding forty others — without switching the whole account off, which punishes everybody.
The balance itself
The last ceiling is the money. At zero, new calls do not start. Read available_cents from GET /v1/balance — it already excludes money held against calls in progress, so it is what your next call can actually draw on.
Call length
A single call is held to 20 minutes. A conversation that runs past that is not a conversation any more — it is a call that failed to end, and it is billed the whole way until somebody notices. The ceiling is what makes that impossible.
Why a call did not start
Every refusal is recorded with a reason you can read in your console's activity log, and the reasons are exactly these:
| Reason | What to do |
|---|---|
insufficient_balance | Top up. The minimum call reserve has to fit before a call starts. |
spend_cap_daily / spend_cap_monthly | Your account cap is reached. It resets at midnight UTC, or on the 1st. |
customer_spend_cap_daily / customer_spend_cap_monthly | A cap you set on that customer. Raise or clear it through the API. |
concurrency_limit | That customer already has as many calls running as you allowed them. |
platform_at_capacity | Kleos itself is full. Nothing is lost; the call starts on a later attempt. |