Rate Limits
These limits apply to the installed-extension routes under /api/extensions. Runtime bridge reads use those routes through Chastify's parent page. Your backend's direct requests also count, using its own authenticated identity.
User-wide programs and OAuth account linking use different route policies. Do not assume this table applies to every /api/apps/* endpoint. Storage quotas, feature cooldowns, and device delivery limits are separate from HTTP request budgets.
Current Extension Buckets
| Bucket | Default per minute | Examples |
|---|---|---|
| Read | 300 | Session context, state, metadata, file reads, regular-action status. |
| Write | 120 | State/metadata changes, requirement progress, attempt tracking, regular-action configuration and consumption, file deletion. |
| Upload | 10 | Runtime image uploads and setup staging uploads. |
| Action | 30 | Lock actions, device commands, custom logs, custom notifications. |
| Token | 30 | Launch-token issuance through the session /auth endpoint. |
Requests share a bucket; these are not separate allowances for each endpoint. The normal distributed limiter uses fixed one-minute windows. Space requests and follow the returned retry hints instead of sending bursts at window boundaries.
Administrators and the site owner can configure per-app overrides. The response headers describe the limit used for that request. Do not hard-code the defaults as a guarantee of available capacity.
How Keys Are Counted
The extension bucket combines the authenticated identity with the target:
| Request | Identity | Target |
|---|---|---|
| Chastify UI or iframe bridge | Signed-in user | Route's extension sessionId, or lockId when present. |
| Extension backend | Developer API key ID | Route's extension sessionId, or lockId when present. |
| Route without either target parameter | Same identity rules | A shared global target. |
For example, one user's session, state, and file reads for the same installed extension consume the same read budget. Multiple users of your backend share that key's budget for the same extension session.
Setup routes use an appId, but the counter's target does not include that ID. Setup requests by the same user can therefore share a bucket across apps, even though an app-specific override determines the limit checked for each request. A lockId query parameter on setup routes does not create a separate route-parameter bucket.
Reduce unnecessary work or discuss legitimate capacity needs with support. Rotating keys or switching identities is not a substitute for handling throttling.
Recommended Client Behavior
Direct HTTP responses normally include:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Maximum requests for the applicable bucket/window. |
X-RateLimit-Remaining | Remaining budget after this request. |
X-RateLimit-Reset | Reset time as an ISO timestamp, not Unix seconds. |
Retry-After | On 429, the number of seconds to wait. |
The limiter's JSON rejection has this shape; the delay varies:
{ "error": "rate_limit_exceeded", "retryAfter": 17 }
For a read, wait at least the supplied delay, add a little random jitter, and use a bounded number of attempts. If no hint reaches your client, pause for a full minute before retrying an extension read. Stop background refresh while the view is closed, and show a retry state instead of spinning indefinitely.
This server-side read-only example assumes a validated current launch context and an app-scoped key stored in the environment. It retries only an explicit 429 from the session read:
async function readSessionWithRateLimitWait(sessionId: string, mainToken: string) {
const developerKey = process.env.CHASTIFY_APP_DEVELOPER_KEY;
if (!developerKey) throw new Error('Configure the app-scoped Developer API key');
for (let attempt = 0; attempt < 3; attempt += 1) {
const response = await fetch(
`https://chastify.net/api/extensions/sessions/${encodeURIComponent(sessionId)}`,
{ headers: {
Authorization: `Bearer ${developerKey}`,
'x-chastify-main-token': mainToken,
} },
);
const data = await response.json();
if (response.ok) return data;
if (response.status !== 429 || attempt === 2) {
throw Object.assign(new Error(data.message ?? data.error ?? 'Session read failed'), {
status: response.status,
data,
});
}
const seconds = Number(response.headers.get('Retry-After') ?? data.retryAfter ?? 60);
const waitSeconds = Number.isFinite(seconds) && seconds > 0 ? seconds : 60;
await new Promise<void>((resolve) => setTimeout(resolve, waitSeconds * 1000 + Math.random() * 500));
}
throw new Error('Session read did not complete');
}
Handle the final error in your request/job boundary. This helper is not a retry wrapper for arbitrary mutations.
An explicit rate-limit rejection happens before that route's handler runs. A timeout, disconnected socket, or server error does not prove a mutation was rejected. Repeating a time change, task assignment, progress increment, or device command can apply it again. Reconcile uncertain outcomes before submitting another effect.
Iframe Bridge Guidance
The runtime bridge exposes error.code and error.message. It currently omits HTTP status, rate-limit headers, and the JSON retryAfter field. The sample ChastifyBridgeClient attaches the bridge code to a rejected error, so check error.code === 'rate_limit_exceeded'; a handler that only checks error.status === 429 will miss it.
For a throttled bridge read, pause refresh for a minute and offer a retry. Do not repeatedly reload the iframe to obtain another token or restart a tight polling loop.
- Reuse context within the current view, but refresh when relevant lock state changes or before presenting time-sensitive choices.
- Combine consumers of the same read instead of having several components poll independently.
- Keep transient UI edits locally. Send a deliberate save to your own backend, and show its confirmed success or failure.
- Stop timers and dispose of the bridge client on unmount.
The bridge is read-only at runtime. Debouncing does not make unsupported bridge writes available; see Iframe Quickstart and API Examples.
Backend Extension Guidance
Keep the Developer key on your server and send the current launch token with installed-extension requests. Serialize operations where the feature requires it, and track the outcome of each intended mutation.
Your own run ID helps prevent duplicate processing in your backend, but generic Chastify mutations do not accept it as an idempotency key. Do not assume a failed HTTP response makes a whole reward/penalty sequence safe to replay. Feature-specific settlement routes can have different contracts.
Upload only on a deliberate submission, retain stable file IDs, and refresh a single signed link instead of repeatedly listing all files. Keep high-frequency telemetry in your own storage. A higher request limit does not remove storage quotas, action permissions, or feature cooldowns.
Which Bucket Should I Expect?
These paths are relative to /api/extensions/sessions/:sessionId:
| Method and suffix | Bucket |
|---|---|
GET session root, /state, /metadata, /regular-actions | Read |
GET /files/capabilities, /files, /files/:fileId | Read |
PUT or PATCH /state; PATCH /metadata | Write |
PATCH /regular-actions/config; POST /regular-actions | Write |
POST /requirements/progress, /attempts/start, /attempts/fail-expired | Write |
DELETE /files/:fileId | Write |
POST /files | Upload |
POST /action, /device-command, /logs/custom, /notifications/custom | Action |
GET /auth | Token |
For setup, POST /api/extensions/apps/:appId/files/stage uses Upload. Setup file reads use Read and staged deletion uses Write.
Overrides and Future Changes
Build clients around returned errors and retry hints. Additional route limits or changes to bucket defaults should not require a new release of your extension. Current overrides are administrator-controlled; an ordinary extension owner cannot grant themselves a higher budget.
When reporting unexpected throttling, include the endpoint, approximate request rate, response code, and non-secret limit/reset values. Never include the Developer key, launch token, or full iframe URL. See Troubleshooting.