Problem
The on_unavailable parameter (ALLOW vs DENY) is an important operational decision, but it's currently only visible in the constructor signature. New users may not discover it until they hit a DynamoDB outage in production.
The docs should proactively explain:
- What happens when the backing store is unavailable
- That this is an inherent trade-off in any external rate limiter (not a zae-limiter-specific flaw)
- How to choose between ALLOW and DENY based on risk profile
Suggested Content
Add a "Failure Modes" section to the getting-started or operations docs:
## What Happens When DynamoDB Is Down?
The `on_unavailable` parameter controls behavior when the backing
store is unreachable:
- `OnUnavailable.ALLOW`: Requests pass through without rate limiting
(fail-open). Use for availability-critical systems where dropping
requests is worse than temporarily losing rate limits.
- `OnUnavailable.DENY`: All requests are rejected with
`RateLimiterUnavailable` (fail-closed). Use for cost-control-critical
systems where unmetered access is unacceptable.
This trade-off is inherent to any external rate limiter — it is not
specific to zae-limiter.
Why This Matters
Users evaluating zae-limiter for multi-tenant platforms (LLM proxies, API gateways) need to understand the failure semantics upfront to make informed architectural decisions. Discovering this only from the API signature is too late.
Problem
The
on_unavailableparameter (ALLOW vs DENY) is an important operational decision, but it's currently only visible in the constructor signature. New users may not discover it until they hit a DynamoDB outage in production.The docs should proactively explain:
Suggested Content
Add a "Failure Modes" section to the getting-started or operations docs:
Why This Matters
Users evaluating zae-limiter for multi-tenant platforms (LLM proxies, API gateways) need to understand the failure semantics upfront to make informed architectural decisions. Discovering this only from the API signature is too late.