Skip to main content
HTTP status: 429 · Title: “Too Many Requests” · Retry-After: computed per response

​
When it fires

You exceeded a rate limit. Authenticated requests are limited per user (shared by every key on the account) and per key; anonymous reads are limited per client IP. Limits use a sliding one-minute window. Authenticated limits depend on your key’s tier. Read the limit that applied from X-RateLimit-Limit. See Rate limits. The same code is also returned during a temporary authentication lockout: after too many failed authentication attempts from one source, requests from it are refused for a period given by Retry-After.

​
Response headers

A 429 from the rate limiter carries:
  • Retry-After: <seconds>, how long to wait before the next request
  • X-RateLimit-Limit: <n>, the limit that applied
  • X-RateLimit-Remaining: 0
  • X-RateLimit-Reset: <unix-seconds>, when the window resets
The detail field names which limit (account or key) refused the request.

​
Why it happens

  • A burst of traffic, such as a polling loop without backoff.
  • A retry storm: every consumer retried at the same instant after a transient failure.
  • Sustained traffic above your tier’s limit.

​
How to fix

  • Honour Retry-After. The TypeScript SDK does this automatically and exposes the value as KashRateLimitError.retryAfterSeconds.
  • Add jitter to retries so multiple consumers don’t synchronise.
  • Replace polling with webhooks where you can.
  • If you hit the limit during normal operation, move to a higher tier. See Rate limits.