Skip to main content
The Clay Public API enforces a per-workspace request rate limit. When you exceed it, Clay returns HTTP 429 and you should back off before retrying.

​
Reading the limit

When a request is rate limited, Clay returns 429 with a Retry-After header (seconds to wait). When available, Clay also sends X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset so you can pace requests before you hit the ceiling. The CLI surfaces the same signal: rate-limited commands exit with code 4, and the error details include retryAfter (seconds), plus limit, remaining, and reset when Clay sends the X-RateLimit-* headers.
  • Treat 429 as retryable. Wait for the Retry-After interval, then retry.
  • Add exponential backoff and jitter when you issue many requests concurrently.
  • Prefer batch and async endpoints over tight polling loops. For async runs, poll the result endpoint at a modest interval rather than as fast as possible.
# CLI: exit code 4 signals rate limiting; back off using details.retryAfter.
clay routines runs list >out.json 2>err.json
status=$?
if [ "$status" -eq 4 ]; then
  sleep "$(jq -r '.error.details.retryAfter // 5' err.json)"
  # ...then retry the command
fi