Rate Limits#

Artery rate-limits per API key, not per IP. Quotas are tier-based and checked in a fixed-window monthly counter (in-memory today; Redis planned for with the same wire shape — pluggable via the RateLimiter interface).

Tier table#

Set the tier on key creation:

bashcurl -X POST https://api.artery.questflow.ai/keys \
  -H "Content-Type: application/json" \
  -d '{
    "name":"trader-bot",
    "userId":"u-1",
    "scopes":["read","stream"],
    "rateLimitTier":"builder"
  }'

The default is free. Tiers can be changed later by an admin token (admin endpoint — planned).

Response headers#

Every successful authenticated response carries the bucket state:

X-RateLimit-Limit:     500000
X-RateLimit-Remaining: 499234
X-RateLimit-Reset:     1780822653
X-RateLimit-Tier:      builder

X-RateLimit-Reset is a Unix timestamp marking the next quota reset (the 1st of next month UTC for monthly quotas).

For enterprise keys the headers report unlimited instead of a numeric limit.

429 handling#

When you hit the limit:

httpHTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Reset: 1780822653
 
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded for tier \"free\" (10000/month)",
    "requestId": "req_..."
  }
}

Upstream limits#

Artery's quota is independent of upstream limits. Even under your Artery quota, you can hit upstream throttling — those surface as upstream_rate_limited (HTTP 429 with provider set):

Artery retries upstream_rate_limited on GET calls automatically (see error handling).

WebSocket subscription limits#

The stream gateway tracks subscriptions per connection. Hitting the cap returns:

json{ "type": "error", "error": "max 1000 subs/conn" }

Burst limits (planned)#

Per-second burst limits are planned with the Redis-backed limiter:

Anti-abuse (planned)#

Sustained burst-limit violations (>10 in a 5-minute window) will trigger a 60-second cooldown. Rotating keys won't bypass it — the cooldown is tied to the underlying user account.

See also#

• Error handling — full envelope + request id
• Authentication — scope + tier configuration