SAAS API RATE-LIMIT POLICY WORKSHEET
Original local teaching example. Checked 2026-10-27.
https://showmeyoursaas.com/articles/rate-limiting/
Reference: https://www.rfc-editor.org/rfc/rfc6585.html
This document and rate-limiting-lab.mjs configure no real service.

COMPLETED SYNTHETIC POLICY
Operation: starting a fictional report.
Identity: synthetic account key; production identity must come from trusted authorization context.
Algorithm: token bucket, one process.
Capacity: 3 tokens.
Refill: 1 token per second, capped at capacity.
Cost: 1 token per request in the printed example.
Clock: explicit nonnegative milliseconds; calls must never move backward globally.
Maximum prepared keys: 1,000 by default; no automatic eviction.
New key at the bound: throw a visible lab error, not an HTTP contract.
Denied request: consumes no tokens; updates the bucket's refill observation time.
Retry suggestion: ceiling of missing-token refill time in milliseconds.
Retry-After seconds: ceiling of that millisecond delay / 1,000.
This suggestion reserves no token.

EXPECTED SEQUENCE FOR ACCOUNT A
Three requests at 0 ms: allowed.
Fourth at 0 ms: denied, 1,000 ms wait.
At 999 ms: denied, 1 ms wait (rounded HTTP seconds = 1).
At 1,000 ms: allowed.
A second account has an independent starting bucket.
After long idle time, available tokens cannot exceed 3.

LIMITATIONS
No distributed atomic counter, persistence, authentication, global billing quota,
job concurrency cap, automatic cleanup, or production failure policy.
A limiter does not establish idempotency or undo accepted work.
Variable costs must be positive and no greater than capacity.
Read the exported function before adapting the example.

BLANK PRODUCTION POLICY
Protected operation and resource:
Authenticated identity / source:
Unauthenticated layer if needed:
Matching and counting rule:
Budget / period / burst:
Cost unit and how it is determined:
Quota policy (separate):
Concurrent-work policy (separate):
Rejection status and safe response:
Retry-After semantics:
Safe client retries / idempotency contract:
Dependency failure behavior:
Atomicity and clock model:
Key expiration / memory bounds:
Authorized test environment and traffic:
Metrics / alert owner:
Stop and recovery process:

CLIENT CHECKLIST
Recognize the actual API contract.
Honor valid retry guidance within a bounded retry/deadline policy.
Consider backoff and jitter when clients may synchronize.
Check whether repeating the operation can duplicate a side effect.
Expose the waiting action and cancellation state clearly.
Do not interpret every 429 as a billing or upgrade event.