Skip to content

Docs: Add Failure Modes section documenting on_unavailable behavior #385

@sodre

Description

@sodre

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions