Skip to main content

​
Rate limits

Clopos Open API v2 applies a three-tier rate limit, each with a 1-minute sliding window and standard IETF RateLimit-* response headers. The tiers layer so that an abusive client IP, a flood of invalid tokens, and a noisy tenant each hit their own ceiling without starving the others.

​
The three tiers

​
Tier 1 — Auth endpoint

60 requests per minute per client IP, applied to POST /v2/auth only.
This is a brute-force guard on credential exchange. It applies per client IP regardless of which integrator_id or brand is in the body. Re-use issued tokens until they are close to expires_at rather than calling /v2/auth on every request — you will exhaust this quota quickly if you do not.

​
Tier 2 — IP pre-limit (flood guard)

600 failed requests per minute per client IP, applied to all authenticated routes.
This tier runs before JWT validation and only counts responses with HTTP status ≥ 400. Successful requests do not decrement the counter at all. It exists to stop invalid-token spam and similar flood patterns without capping legitimate traffic from integrators that fan many brands through a single outbound IP. In practice, you will only see this limit if your client is repeatedly sending malformed, expired, or unauthorized requests from the same IP. Fix the request and it stops counting.

​
Tier 3 — Per-tenant limit

300 requests per minute per integrator_id:brand pair, applied to all authenticated routes.
This is the main quota you will plan against. It runs after JWT validation and keys on the verified JWT payload, so:
  • Minting new tokens for the same (integrator_id, brand) does not reset the counter — all tokens share the same budget.
  • The budget is per (integrator_id, brand) pair. A single integrator serving many brands gets a separate 300 req/min budget for each brand.
  • Distributing traffic across many workers or processes does not multiply the quota — the limit is enforced centrally.

​
Response headers

Every authenticated response includes standard IETF RateLimit-* headers for the tier that is currently most constrained, so you can track your budget without parsing bodies:
HeaderMeaning
RateLimit-LimitTotal requests allowed in the current 1-minute window for this tier.
RateLimit-RemainingHow many requests you can still make before being throttled.
RateLimit-ResetSeconds until the current window resets.
HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Limit: 300
RateLimit-Remaining: 214
RateLimit-Reset: 42
Inspect these on every response and slow down proactively when RateLimit-Remaining gets low — it is always cheaper than recovering from a 429.

​
What a 429 looks like

When any tier is exceeded, the API responds with 429 Too Many Requests. Back off for at least RateLimit-Reset seconds before retrying. 
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 300
RateLimit-Remaining: 0
RateLimit-Reset: 37

​
Handling throttling

A few patterns work well in practice:
  1. Watch the headers, not the errors. Adjust your request cadence based on RateLimit-Remaining rather than waiting for a 429.
  2. Back off exponentially on retry. If you do get throttled, wait at least RateLimit-Reset seconds before retrying, then double the wait on each consecutive failure.
  3. Re-use JWTs. Call /v2/auth at most once per token lifetime (~1 hour). Hammering the auth endpoint wastes your Tier 1 budget and does nothing for your Tier 3 budget.
  4. Fix errors fast. If you hit Tier 2, it means something in your client is spamming invalid requests. Fix the root cause — retries against a broken request only burn your IP budget.
  5. Batch where possible. List endpoints support pagination with limit up to 200 for most resources — one larger list call is always cheaper than many small ones against your Tier 3 budget.
  6. Avoid tight polling loops. Until webhooks ship, polling is sometimes unavoidable — but keep intervals reasonable (seconds, not milliseconds) and use date[0] / date[1] or sort filters to fetch only what changed.
  7. Use a single integrator per workload. Splitting traffic across many integrators to multiply the quota is a policy violation; Clopos monitors for it.

​
Need a higher limit?

If 300 requests per minute is not enough for a legitimate use case (for example, a large delivery marketplace or a migration batch job), contact Clopos support at [email protected] with your integrator_id, the brand(s) involved, and a description of the workload. Quotas are adjusted on a per-tenant basis.