Developer Platform

Limits, rate limits, and idempotency

How clients should handle quotas, throttling, payload boundaries, retries, and safely repeated writes.

Developer limits should be explicit and observable. The API must fail clearly when a client exceeds a rate, payload, plan, storage, or execution boundary; it should never silently drop records or truncate a mutation.

Rate limiting

When a caller exceeds its current request allowance, the gateway returns 429 Too Many Requests. Honor Retry-After, which can contain nonnegative whole seconds or an HTTP-date. Wait at least that long, add jitter, and bound retry attempts and total waiting time. Missing or malformed retry hints do not authorize an immediate retry loop.

The checked-in Developer Gateway defaults to 60 requests per 60-second window for each verified caller partition. This is an outer traffic limit, not 60 requests for every endpoint or an entitlement to unlimited writes. Module operations also have separate per-caller, app and module limits:

Operators can configure these defaults. A request must pass every applicable limit; splitting calls across module routes does not remove the outer limit. Follow the actual response headers and current environment contract. Pace list/detail traversal and bound concurrency. A pagination endpoint is not a bulk-write endpoint; use only operations actually declared by the pinned OpenAPI contract.

Idempotent writes

Use an idempotency key only when the exact operation documents one; adding an invented header does not make a write safe to repeat. Preserve the selected record scope and exact concurrency revision. After a network failure or an unusable write receipt, inspect the authoritative record or documented operation status before deliberately submitting again. Never automatically repeat a create, payment, invitation, archive, or webhook retry.

Plan and resource limits

Some limits are application or subscription entitlements rather than traffic controls — for example storage pools, AI budgets, or feature access. Those failures should use structured error codes and include a safe explanation of the resource that needs attention.

Payload and execution limits

Large imports, exports, and long-running actions should move to asynchronous operation resources. Container-backed endpoints also have explicit execution and payload boundaries so a custom service cannot tie up the gateway indefinitely.

The current record-search contract bounds pageSize to 1–100 and query text to 400 characters. Every other request/list bound is defined by its OpenAPI schema or environment response; clients must validate against that contract instead of assuming the record-search values apply globally.

See Pagination, filtering, rate limits, and versioning for copyable request and traversal behavior.

SDK and Kit recovery

The repository SDK candidates retry eligible reads once by default, only after a valid 429 hint. Connector, delegated runtime, design, generated module and Builder platform clients retry GET/HEAD only; the separate Headless SDK also recognizes its explicitly read-only POST record search. Other methods are never automatically repeated. Each client has its own cooldown, at most 60 seconds of automatic waiting and up to 250 milliseconds of added jitter by default. Longer server delays are surfaced intact instead of shortened. Cancellation stops the waiting caller. Other HTTP errors and network failures are not automatically retried.

For cross-origin browser integrations, the API must expose both Retry-After and Date through its reviewed CORS policy. The SDK can use the response Date to interpret an HTTP-date retry hint against the server clock. Neither header is a CORS-safelisted response header; seeing one in the browser's network inspector does not mean JavaScript can read it. Verify the deployed policy before relying on this behavior. The repository Gateway change is a source candidate until separately activated.

The Design client remains server-only and requires its documented Builder credential. Use the reviewed delegated-user flow for browser-capable clients; retry support does not make a long-lived app or Builder key safe to embed in a browser.

Writes are never automatically repeated. The reference Kit preserves the draft and displays a countdown; finishing the timer does not submit the form. If a response was lost or malformed, the uncertain-write lock remains until the user refreshes and inspects authoritative state. This SDK/Kit behavior is staged repository work; the published Developer Kit is unchanged until a new reviewed release is published.

The repository reference client's countdown follows elapsed time from response-header receipt, including time spent reading a slow response body. Changing the computer's wall clock does not shorten or extend that wait. Timer completion still requires a deliberate action, and an uncertain-write lock still requires explicit read recovery.

Capability review: 2026-10-31. See current features and setup requirements, the generated API Map and first-class module inventory.