`rate_limited`

HTTP	When
429	The workspace exceeded the bucket’s sliding 60-second window.

The response includes:

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 17

Retry-After is in seconds. Sleep at least that long, then retry. Limits are per workspace, not per key — adding more keys for the same workspace doesn’t increase your budget. See conventions.md §rate-limits for the bucket sizes. To avoid 429s in steady-state traffic:

Pre-throttle. Watch X-RateLimit-Remaining and slow yourself down before you hit zero.
Batch where possible. Use the largest reasonable limit (up to 200) on list endpoints to halve the number of requests.
Cache aggressively for read-heavy paths. Most /v1/projects responses are stable enough to cache for a few minutes in your client.

If you’re seeing 429s in normal traffic and need a higher limit, email support with your typical request rate and use case — we’ll discuss plan-specific quotas.

The one case where retrying is wrong

MCP’s publish_post also returns rate_limited, but for the agent publish cap — 5 publishes per user per rolling 24 hours, not a 60-second bucket. There is no useful Retry-After for it, and the budget will not free up in seconds. Do not retry: schedule the post instead, or publish it from the dashboard. See mcp.md §5.