Problem
The performance documentation shows both normal path and speculative write costs, but doesn't emphasize that speculative writes are enabled by default. A reader scanning the cost table sees the normal path first and assumes that's the default cost.
This led to a concrete misunderstanding: estimating 10M non-cascade calls at $7.50/month (normal path: 1 RCU + 1 WCU per call) when the actual default cost is ~$6.88/month (speculative: 0 RCU + 1 WCU per call, with ~5% fallback).
Suggested Changes
-
Reorder the cost table to lead with speculative write costs since they are the default behavior.
-
Add a callout at the top of the performance section:
> **Note:** Speculative writes are enabled by default. The costs
> below reflect the default configuration. To use the normal
> read-before-write path, set `speculative_writes=False`.
- Add a quick-reference cost summary for common scales:
| Scale |
Non-Cascade (default) |
Cascade (default) |
| 1M calls/month |
~$0.69 |
~$1.29 |
| 10M calls/month |
~$6.88 |
~$12.85 |
| 100M calls/month |
~$68.80 |
~$128.50 |
(Assuming ~95% speculative hit rate, on-demand pricing)
Why This Matters
Cost estimation is a key factor when evaluating rate limiting solutions. If the docs lead with the more expensive path, users may overestimate costs and choose a different solution unnecessarily.
Problem
The performance documentation shows both normal path and speculative write costs, but doesn't emphasize that speculative writes are enabled by default. A reader scanning the cost table sees the normal path first and assumes that's the default cost.
This led to a concrete misunderstanding: estimating 10M non-cascade calls at $7.50/month (normal path: 1 RCU + 1 WCU per call) when the actual default cost is ~$6.88/month (speculative: 0 RCU + 1 WCU per call, with ~5% fallback).
Suggested Changes
Reorder the cost table to lead with speculative write costs since they are the default behavior.
Add a callout at the top of the performance section:
(Assuming ~95% speculative hit rate, on-demand pricing)
Why This Matters
Cost estimation is a key factor when evaluating rate limiting solutions. If the docs lead with the more expensive path, users may overestimate costs and choose a different solution unnecessarily.