Quotas & rate limiting

Credit balance (402)

Billing is prepaid: every request checks your credit balance first. When the balance is at or below zero (and past any configured grace window), requests receive 402 Payment Required:

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_balance",
    "message": "Insufficient credit balance. Please top up your account to continue.",
    "action": "topup",
    "top_up_url": "https://app.cloakapi.io/billing"
  }
}

Top up in the portal under Billing.

Token quotas (429)

Independent of balance, every tenant has hourly and daily token budgets (per pricing segment, with per-key overrides). Requests over budget receive 429 with a Retry-After header and one of two codes:

{
  "error": {
    "type": "rate_limit_error",
    "code": "hourly_quota_exceeded",
    "message": "Hourly token quota exceeded. Retry after the top of the hour.",
    "quota": { "window": "hourly", "limit": 1000000, "used": 1000000 }
  }
}

(daily_quota_exceeded is the daily-window equivalent.) Successful responses carry X-CloakAPI-Quota-Hourly-Remaining and X-CloakAPI-Quota-Daily-Remaining headers. Requests routed to local Ollama are never charged or quota-blocked.

Rate limits

Two scales, both sliding-window:

Scale	Default per (tenant, capability)	Header
60s	60 req/min	RateLimit-Limit-Minute
3600s	1000 req/hr	RateLimit-Limit-Hour

Public endpoints (/api/v1/receipts/verify, /.well-known/*) have their own per-IP limits (30 req/min for verify, 120 req/min for discovery).

Throughput & concurrency

The 60 req/min above is the floor for a new, unverified tenant. Once your account is verified, the per-tenant ceiling rises to 600 req/min. Two further ceilings bound abuse without penalising a single legitimate tenant:

Ceiling	Default	What it bounds
Per tenant (unverified)	60 req/min	New accounts before verification
Per tenant (verified)	600 req/min	The working ceiling for a verified account
Per organisation	600 req/min	Aggregated across every key the org holds — issuing more keys does not multiply quota
Per source IP (/64)	300 req/min	Shared egress can’t rotate keys past the org ceiling

The gateway imposes no fixed concurrent-connection cap; sustained concurrency is governed by the per-minute ceilings above and, for volume, by the hourly and daily token budgets in Token quotas. There is no array/batch request endpoint — high-volume pipelines fan out parallel requests under the rate ceiling and use Idempotency-Key for safe retries. Successful responses carry RateLimit-Limit-Minute, RateLimit-Limit-Hour, X-CloakAPI-Quota-Hourly-Remaining and X-CloakAPI-Quota-Daily-Remaining so a pipeline can back off before it is throttled.

Production / batch limits. Your rate ceiling is stamped per-key and can be raised per tenant. For batch or data-engineering workloads that need sustained volume above the verified 600 req/min ceiling, these are provisioned rather than self-serve — email support@cloakapi.io with your target sustained req/min and daily token volume and we set production limits so we can line up matching upstream provider capacity. Limits are not finalised per-account until agreed, so contact us for production numbers rather than assuming the defaults above are your cap.

The free demo relay on the marketing site is a separate try-before-register surface capped at 5 messages/IP/day under a global daily budget — it is not a throughput path.

Idempotency

Send Idempotency-Key: <uuid> with any POST request. The gateway caches the response for 24h keyed by (tenant, idempotency_key). Retries with the same key replay the same response — including the same receipt — and do not consume quota.

This is the recommended pattern for any production caller, not least because it makes failover safe to retry from the SDK.