> For the complete documentation index, see [llms.txt](https://docs.openg2p.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openg2p.org/products/open-agri-stack/composite/rate-limiting.md).

# Rate Limiting

Limiting request rates.

**Status: built** (edge limit and per-partner limit); partner-aware edge limits and quotas are later.

## Three layers

Good practice limits requests in up to three places. Each catches what the others cannot.

| Layer                   | Where                              | Keyed on                                                                                         | What it is for                                                                                                  |
| ----------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Edge**                | The ingress gateway (Istio, Envoy) | Route, client IP, or everything                                                                  | Cheap. Stops floods before they reach a service; knows nothing about partners                                   |
| **Identity-aware edge** | The ingress gateway                | The caller, read from something the gateway can trust: a JWT claim or an mTLS client certificate | Per-caller limits without touching the service                                                                  |
| **Application**         | The service                        | Business identity: partner and use case                                                          | Business rules (rate per partner per use case, quotas). Counters in shared storage so every pod counts together |

The identity-aware edge layer is **not possible today**: partners sign inside the request body (a detached JWS over the envelope, `header.sender_id`), which the gateway cannot verify. Only the Composite, which checks the signature against [Partner Management](https://docs.openg2p.org/platform/platform-services/partner-management.md), knows who is calling.

## What Agri Stack does

1. **Edge limit at the ingress gateway.** The Composite chart adds a local rate limit (Envoy token bucket) on the Composite's use-case route (`/composite/v1/use-cases`) at the shared Istio ingress gateway. It counts all partners together, per gateway pod. Over the limit the gateway answers `429` with the header `x-local-rate-limit: true` (plain text, not a signed envelope). **Off by default** (120 requests per minute when on): the filter has to live in the gateway's namespace, `istio-system`, which a user limited to their own namespace cannot write. How to do this within a namespace is open. To turn it on: [Production: edge rate limit](https://docs.openg2p.org/products/open-agri-stack/deployment/production.md#edge-rate-limit).
2. **Per partner, per use case, in the Composite.** Each use case sets `limits.rate_per_partner` (e.g. `60/min`). The Composite applies it after the signature and use-case policy checks: a token bucket per (partner, use case) in Redis (the commons Redis), so every pod and worker draws from the same bucket. Over the limit: `429 rate_limited`.

If Redis is unreachable, each worker process falls back to its own in-memory bucket and logs a warning. This is deliberate: **availability over exactness**. A Redis outage never fails a partner call; the limit only loosens (up to pods × workers × the rate) until Redis answers again.

Settings: [Composite deployment](https://docs.openg2p.org/products/open-agri-stack/deployment/exchange/composite-chart-settings.md#scaling-and-rate-limits).

## Later

* **Per-partner limits at the edge**, if partner identity moves to mTLS client certificates or a JWT the gateway can read.
* **Daily quotas** per partner per use case (`limits.daily_quota_per_partner`), counted in the same Redis.
* **Counting calls for charging** is metering, not rate limiting: [API Metering and Billing](https://docs.openg2p.org/products/open-agri-stack/roadmap/api-metering.md).
* **Per-farmer fetch frequency**: the policy's `max_fetch_frequency` (how often a partner may fetch the same farmer's data).

The policy's `data_life` is a retention term for the partner (how long it may keep the data), not a rate. It is recorded only.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openg2p.org/products/open-agri-stack/composite/rate-limiting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
