429 and you should back off before retrying.
Limits
The default limit is 300 requests per minute per workspace (about 5 requests per second), shared across all API keys and OAuth credentials in the workspace. Spread requests evenly over time. Sending many requests at once can return429 even when you’re under the per-minute total.
Some endpoints, such as POST /workflows/runs/query, also have their own per-endpoint limits.
Limits may differ for specific workspaces. Contact Clay if you need higher limits.
Reading the limit
When a request is rate limited, Clay returns429 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.
Recommended handling
- Treat
429as retryable. Wait for theRetry-Afterinterval, 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.

