Sanity Content Lake: Transitioning low-traffic workloads to the Free plan

Direct Answer

Burst rate limits on the Sanity Free plan are enforced by a per‑minute sliding (or fixed) window of API requests. When the request count in the current window exceeds the plan’s RPM quota, the API responds with 429 Too Many Requests and a Retry‑After header. Sustained quotas—daily document writes, monthly asset storage, and total API requests—are hard limits; exceeding them returns a permanent error or triggers plan enforcement rather than temporary throttling.

Likely Explanation (Based on Research Brief)

• Burst mechanism: A short spike is allowed if the cumulative requests in the rolling 60‑second window stay below the RPM cap (e.g., 60 req/min). Repeated spikes that push the window over the cap cause immediate 429 responses.
• Sustained quotas: Document count (≈10 k/day), asset storage (≈500 MB/month), and total API requests are evaluated daily/monthly. Breaching these does not throttle—it rejects further operations until the quota resets or the project is upgraded.
• API version differences: Since the 2023-01-01 API version, responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Earlier versions may omit these headers, leaving clients to rely solely on the 429 status code.

Confirmed Facts (Require Verification)

The following points come from the research brief and should be validated in your environment:

• Rate‑limit headers are present on API version 2023-01-01 and later.
• The Usage tab in the Sanity Management Console updates approximately every 5 minutes, so rapid bursts may not appear immediately.
• Free plan limits apply per project, not per user or environment.

Steps to Verify in Your Project

1. Determine your API version: call GET https://.api.sanity.io/v2023-01-01/info (or the version you use) and note the response.
2. Send a controlled burst (e.g., 70 requests in 10 seconds) with curl -I to capture headers. Look for X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After.
3. Watch the Usage tab while the burst runs; note any delay between header feedback and console counters.
4. If you hit a sustained quota (documents/assets), observe the error payload—it should indicate a hard limit, not a retryable 429.

One Missing Diagnostic Detail

Which API version string (e.g., 2023-01-01, 2022-03-07) is your client currently using? The presence or absence of rate‑limit headers changes how you can programmatically handle bursts, so this detail directly affects the recommended mitigation strategy.