What distributed rate-limit invariants prevent agents from collectively exceeding shared API quotas?

**Date of Record:** 2026 October 27 **Scope:** Applies when multiple agentic sessions use a shared API quota (organization-wide limit, shared tenant account, or pooled credits), and the sessions must coordinate to stay within the quota despite not directly communicating about rate-limit state. Does not apply to per-session quotas or unlimited APIs.

Core Distinction

The separation between **per-session rate limiting** (each session respects its own limit) and **aggregate rate limiting** (the collective usage stays under the shared quota). Relying on per-session limits creates the **Collective Quota Exhaustion**: each session respects its own limit, but the sum of all sessions' usage exceeds the shared quota, the API throttles globally, and every session's traffic is degraded simultaneously.

What Was Observed

In shared-quota agent architectures, failing to coordinate produces three primary failure modes:

  1. **Burst Collision:** Three sessions each plan a burst of 100 requests per minute. Individually, each is within its per-session limit. Collectively, 300 RPM exceeds the 200 RPM shared quota, and all requests are throttled.
  2. **Fairness Collapse:** One session consumes 80% of the shared quota, the others are throttled immediately, and their tasks fail even though they were following their per-session policies.
  3. **Throttle Cascade:** The API returns 429 to one session, the session retries with backoff, but its retries consume more of the shared quota, causing more 429s to other sessions, amplifying the cascade.

Recorded Elements

  1. **`shared_quota_consumption_receipt`:** A cryptographic, distributed receipt of the current aggregate quota consumption, updated by all sessions and readable by all sessions before they act.
  2. **`per_session_reservation_signature`:** Each session's cryptographic reservation of a slice of the shared quota, preventing simultaneous claims that would exceed the total.
  3. **`session_fair_share_receipt`:** The exact fair share allocation (e.g., "with 5 active sessions, each session gets 20% of the shared quota") and the current session count, allowing sessions to know their fair share.
  4. **`burst_coordination_receipt`:** For any session planning a burst, the cryptographic proof that the burst fits within its fair share AND within the remaining aggregate quota.

Condition of Validity

* **Applies when:** Multiple sessions share an API quota, per-session limits are insufficient, and collective exhaustion causes real harm. * **Does not apply when:** Each session has its own dedicated quota, or the shared quota is unlimited.

Decision Boundary

  1. **Is the session using a shared-quota API?** If no, standard rate limiting applies. If yes, proceed.
  2. **Is the `shared_quota_consumption_receipt` current (within acceptable freshness)?** If no, the aggregate state is unknown. The session must query or defer.
  3. **Does the session's planned usage fit within its `session_fair_share_receipt`?** If yes, proceed. If no, the session must wait, reduce, or request reallocation.
  4. **Conversely, when can a session use quota without coordination?** Only when its usage is well below its fair share and the remaining aggregate headroom is verified to be large (e.g., >80% of quota available).

Operational Effect

  1. **Quota Preservation:** Distributed coordination prevents simultaneous over-consumption.
  2. **Fairness Enforcement:** Explicit fair share prevents one session from starving others.
  3. **Cascade Prevention:** Burst coordination detects collective bursts before they trigger throttling.
from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class QuotaVerdict(Enum):
    DEDICATED_QUOTA = auto()
    WITHIN_FAIR_SHARE = auto()
    EXCEEDS_FAIR_SHARE = auto()
    INSUFFICIENT_AGGREGATE_HEADROOM = auto()

@dataclass(frozen=True)
class SharedQuotaState:
    shared_quota_limit: float
    aggregate_consumed: float
    active_session_count: int
    session_planned_usage: float
    receipt_freshness_sec: float

@dataclass(frozen=True)
class QuotaPolicy:
    max_receipt_staleness_sec: float
    fairness_weight: float  # 1.0 = equal shares, <1 = lenient, >1 = stricter

@dataclass(frozen=True)
class QuotaManifest:
    verdict: QuotaVerdict
    fair_share: float
    directive: str
    manifest_digest: str

class DistributedRateLimitGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_usage(
        cls, state: SharedQuotaState, policy: QuotaPolicy
    ) -> QuotaManifest:
        
        # Gate 1: Receipt freshness
        if state.receipt_freshness_sec > policy.max_receipt_staleness_sec:
            return QuotaManifest(
                verdict=QuotaVerdict.INSUFFICIENT_AGGREGATE_HEADROOM,
                fair_share=0.0,
                directive=f"HALT: Aggregate receipt {state.receipt_freshness_sec:.0f}s stale.",
                manifest_digest=cls._hash(f"STALE:{state.receipt_freshness_sec:.0f}")
            )

        # Gate 2: Fair share computation
        if state.active_session_count <= 0:
            fair_share = state.shared_quota_limit
        else:
            fair_share = (state.shared_quota_limit / state.active_session_count) * policy.fairness_weight

        # Gate 3: Fair share check
        if state.session_planned_usage > fair_share:
            return QuotaManifest(
                verdict=QuotaVerdict.EXCEEDS_FAIR_SHARE,
                fair_share=fair_share,
                directive=f"THROTTLE: Planned {state.session_planned_usage:.0f} > fair share {fair_share:.0f}.",
                manifest_digest=cls._hash(f"EXCEED_FAIR:{state.session_planned_usage:.0f}")
            )

        # Gate 4: Aggregate headroom
        remaining = state.shared_quota_limit - state.aggregate_consumed
        if state.session_planned_usage > remaining:
            return QuotaManifest(
                verdict=QuotaVerdict.INSUFFICIENT_AGGREGATE_HEADROOM,
                fair_share=fair_share,
                directive=f"HALT: Planned {state.session_planned_usage:.0f} > headroom {remaining:.0f}.",
                manifest_digest=cls._hash(f"NO_HEADROOM:{remaining:.0f}")
            )

        # Gate 5: Within bounds
        digest = cls._hash(json.dumps({
            "fair_share": f"{fair_share:.1f}",
            "remaining": f"{remaining:.1f}",
            "planned": f"{state.session_planned_usage:.1f}",
            "sessions": str(state.active_session_count)
        }, sort_keys=True))
        
        return QuotaManifest(
            verdict=QuotaVerdict.WITHIN_FAIR_SHARE,
            fair_share=fair_share,
            directive=f"PROCEED: Planned {state.session_planned_usage:.0f} within fair share {fair_share:.0f}.",
            manifest_digest=digest
        )