Rate limits

Default per key: 1000 req/hour, 10000 req/day (fixed windows, rate_limit_buckets);
per-API override rate_limit_per_hour. 429 carries Retry-After seconds. Limits are
documented in /docs and surfaced in the dashboard key UI.

§1.4 requires these limits to be surfaced in the dashboard key UI. These are documented defaults, not measured usage or a reading of your account's current configuration.

A refused request is not executed: rate_limit is checked in the pipeline before the spreadsheet is read, so a 429 costs you no rows and no Google call. The code is rate_limited, the category is rate_limit, and the wait is in the header.

curl 'https://sheet.zaber.tech/api/v1/<api-id>?limit=1000' \
  -H "Authorization: Bearer sz_live_…"

HTTP/1.1 429 Too Many Requests
Retry-After: <seconds>

{
  "error": {
    "code": "rate_limited",
    "message": "<text — not specified by the contract>",
    "category": "rate_limit"
  }
}

• Wait for the header, not for a guess. §1.4 puts the seconds in Retry-After. Internally, §4.4 has the same number as fields.retry_after so a route and a server action read one value; on /api/v1 there is no documented fields member, so read the header.
• There are no remaining-quota headers to read. The contract documents Retry-After and nothing else — no X-RateLimit-* set, no remaining/limit/reset triple. Build no backoff logic on numbers you cannot get.
• Retrying inside the window repeats the refusal. rate_limit is one of the two documented retryable categories, and both of them mean “later”, not “again now”.

The counters are a Postgres table, not a cache. docs/database-schema.md lists rate_limit_buckets among the standalone counters: its primary key is a composed text string rather than a foreign key to a key or API row, so the bucket a request spends is named by that string alone.

rate_limit_buckets
  bucket_key      text PK   "{scope}:{id}:{window}"   e.g.  key:<keyId>:h
  count           int  NOT NULL
  window_start    timestamptz NOT NULL

Each request is one upsert: insert the bucket, or on conflict add one to count and reset window_start only when the interval has already elapsed. docs/database-schema.md calls that a single round-trip fixed-window counter and docs/plan.md D13 records the reasoning — a Postgres counter table with atomic upsert for the hour and day windows, per key and per public API, chosen over a Redis vendor at this scale, with request logs already available for analytics. The same D13 row names Upstash as the documented scale-up path, and docs/security.md §6 repeats it as the answer to the burst trade-off below.

The numbers on this page are the platform's documented defaults. They are not a customer's settings, and today there is no documented way to raise a default: theupdatePlatformSettings action that would take defaultRateLimits is listed in §2 and marked blocked in §4.10 — no platform-settings table exists among the eleven, and the only rate-limit column in the schema is the per-API rate_limit_per_hour.

• What you can set: a lower hourly ceiling for one endpoint, via rate_limit_per_hour. docs/database-schema.md describes write verbs on the API row separately, and the dashboard surfaces the count of endpoints that override.
• What you cannot set, per the docs: the day ceiling, a per-key override, or a platform-wide change. Nothing in §1.4, §4.6 or docs/database-schema.md offers them, and §4.10 is explicit that the settings action is not typeable until a storage decision exists.
• What this page will not do: print a “contact us for higher limits” promise, a tier table, or a number that is not in the contract. No documented route to an increase exists in §1.4, §4.6 or §4.10, so this page offers none either.

A 429 means you asked too often. These mean you asked for too much at once, and they refuse with different codes — worth separating before you write a retry loop.

• A fixed window can burst roughly twice at its edges. docs/security.md §6 lists this as an accepted trade-off, with the reasoning that the windows are small and the Upstash upgrade path is documented. In practice: 1000 requests just before the hour turns over and 1000 just after is a legal burst of 2000 in an hour of wall-clock time — so the day ceiling, not the hour one, is what bounds a runaway client.
• The in-memory invitation note is superseded. docs/security.md §6 still describes a cold-instance reset, but contract §2 explicitly requires a DB fixed-window invitation bucket shared across instances. That older trade-off is not the current contract.
• “Sliding-window” appears in one document and not in the others. docs/architecture.md’s engine walkthrough describes step 4 as sliding-window counters, while §1.4 and docs/database-schema.md both say fixed windows and describe a fixed-window upsert. This page follows §1.4; the discrepancy is recorded for the maintainers rather than smoothed over.
• Buckets are pruned, limits are not journalled. docs/database-schema.md notes rate_limit_buckets is pruned nightly alongside the logs, so there is no historical record of when you were limited. api_request_logs is where a 429 shows up — with the error_category column that stores rate_limit as one of its six documented values.

This section is advice, and it says so. What the contract gives you is fixed windows, a documented page size, and one honest response header; the rest follows from those.

• Page instead of polling. limit and offset (or page/per_page, which §1.3 defines as offset = (page-1)*per_page) get a large tab through 1000 requests an hour. Mixing the two families is a documented 400.
• Ask for the columns you use. fields/select is applied after filtering, so it shrinks the response, not the counter.
• One in-flight request per key, and back off on 429 by Retry-After. rate_limit and google are the two retryable categories; treat the other four as “changing nothing”.
• Remember whose quota you are spending. Every read and write runs on the spreadsheet owner's Google grant, so a client that hammers the API spends a person's upstream quota as well as its own bucket.