Rate Limits

Scenema enforces a per-workspace request rate limit tied to the plan the workspace is on. The ceiling is generous enough that any reasonable client will never see it, and low enough to protect the API from runaway loops.

Per-plan ceilings

The limit applies to the workspace as a whole, not to any single key. Creating more keys does not raise your ceiling. All requests authenticated with any key on the workspace share the same counter.

What a rate-limited response looks like

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED"
}

• Retry-After is the number of seconds until you can retry. Standard HTTP clients honor this automatically.
• code: RATE_LIMITED distinguishes rate-limit failures from other 429s in the (unlikely) event we add other 429 conditions later.

Handling limits in a client

Best case: use an HTTP client that respects Retry-After out of the box. Examples:

• curl: curl --retry 5 --retry-delay 2 --retry-max-time 300 ...
• Python requests with urllib3.util.Retry.
• Node’s undici retry adapter.

Manual pattern in JavaScript:

async function callWithBackoff(url, opts, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await fetch(url, opts);
    if (res.status !== 429) return res;
    const retryAfter = Number(res.headers.get('retry-after') ?? '1');
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  }
  throw new Error('Rate limit backoff exhausted');
}

Plan changes and rate limits

Plan changes propagate to your workspace immediately. Upgrading raises the ceiling. Downgrading or cancellation lowers it. You do not regenerate keys to pick up new ceilings; the change is server-side and invisible to clients other than the raised or lowered limit.

Distinguishing 429 from other error classes

See Errors for the full status code and code list.