---
schema_version: "1"
id: d63ab5ff4b88abdaf9b96debe3b9f8083026b605fa03a1c1bb3fec562cb498c0
title: A2A v1 Token Based Rate Limit Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/latest/policies-included-a2a-v1-token-rate-limit.md
canonical_url: https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-token-rate-limit
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 9dccbfa1b1649e119c788761c66687cdf81862841b98c6b03630de15c6c13f16
description: MuleSoft Documentation Site
release: "1.14"
latest: true
---
---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Token Based Rate Limit Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Token Based Rate Limit</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rate limits v1 A2A agent usage of upstream resources</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-token-rate-limit-release-notes">A2A v1 Token Based Rate Limit Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>429 - Too Many Requests: Token limit exceeded, requests are blocked until the current window finishes</p></td></tr></tbody></table>

## Summary

The A2A v1 Token Based Rate Limit policy enforces token-based rate limiting on A2A v1.0 agent
requests across all transport protocols: JSON-RPC, HTTP+JSON, and gRPC. This policy counts tokens
using the GPT-4o-mini tokenizer model and enforces a per-key budget over a configurable time window.

The policy counts tokens from both request and response payloads:

- **Request tokens** - Counted from `SendMessage` and `SendStreamingMessage` requests. Only text
  parts (`Part::Text`) and data parts (`Part::Data`) are counted. File parts (`Part::File`) aren’t
  counted since file URLs or base64 content aren’t sent directly to the LLM.

- **Response tokens** - Counted from response content including message parts, status messages,
  artifacts, and Server-Sent Events (SSE) streams. Response tokens are counted toward the same limit
  to ensure a single conversation can’t exceed the limit by sending tiny prompts.

Read-only methods (`GetTask`, `ListTasks`, push notification methods, agent card requests) and
non-A2A traffic pass through without consuming tokens.

When the token limit is exceeded, the policy blocks the request and returns a
`429 - Too Many Requests` error with rate limit headers indicating the limit, remaining tokens, and
reset time.

> [!NOTE] This policy is designed for A2A v1.0 traffic only. For pre-v1.0 A2A traffic, use the
> [A2A Token Based Rate Limit Policy](https://docs.mulesoft.com/gateway/latest/policies-included-a2a-token-rate-limit).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Token Based Rate Limit policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum Tokens</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Maximum number of tokens allowed per resolved key within the specified time period. Must be a positive integer of 1 or greater.</p></div></div></td></tr><tr><td><div><div><p>Time Period (ms)</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Time period in milliseconds for the rate limit sliding window. Minimum value is 1000 milliseconds (1 second). The limit refills once the window rolls.</p></div></div></td></tr><tr><td><div><div><p>Key Selector</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>DataWeave expression that selects the key for rate limiting. This creates independent rate limit counters for each unique value resolved by the expression. The expression is evaluated once per request before A2A parsing.</p></div><div><p>Common examples:</p></div><div><ul><li><p><code>#[attributes.headers['ClientId']]</code>: Rate limit per client ID</p></li><li><p><code>#[attributes.principal]</code>: Rate limit per authenticated user</p></li><li><p><code>#[attributes.headers['X-Forwarded-For']]</code>: Rate limit per source IP address</p></li></ul></div><div><p>If the expression fails to resolve to a string, the policy returns HTTP 400 (Bad Request).</p></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A v1 Token Based Rate Limit policy uses a sliding-window rate limiting algorithm. Each unique
key (resolved by the **Key Selector** expression) has its own independent token budget and time
window.

When a request arrives:

1.  The policy resolves the **Key Selector** expression to determine the rate limit key

2.  For `SendMessage` and `SendStreamingMessage` requests, the policy parses the A2A v1.0 message
    and counts request tokens

3.  The policy checks if sufficient tokens remain in the limit for this key

4.  If tokens are available, the request proceeds to the backend

5.  Response tokens are counted toward the same limit

6.  If the limit is exhausted, subsequent requests are rejected with HTTP 429 until the window
    resets

### Token Counting

The policy uses the GPT-4o-mini BPE tokenizer model to count tokens. Within `SendMessage` and
`SendStreamingMessage` requests:

<table><colgroup><col> <col></colgroup><thead><tr><th>Part Type</th><th>Token Counting Behavior</th></tr></thead><tbody><tr><td><div><div><p><code>Part::Text</code></p></div></div></td><td><div><div><p>Yes: The <code>text</code> value is tokenized and counted</p></div></div></td></tr><tr><td><div><div><p><code>Part::Data</code></p></div></div></td><td><div><div><p>Yes: The JSON-serialized <code>data</code> payload is tokenized and counted</p></div></div></td></tr><tr><td><div><div><p><code>Part::File</code></p></div></div></td><td><div><div><p>No: File URLs (<code>url</code>) and base64 content (<code>raw</code>) aren’t counted since they aren’t sent directly to the LLM</p></div></div></td></tr></tbody></table>

Response tokens are counted from:

- Direct message parts in responses

- Status message parts

- Artifact parts

- Server-Sent Events (SSE) stream data (billed once per event)

For more information about the tokenizer model, see the
[OpenAI Platform Tokenizer](https://platform.openai.com/tokenizer).

### Response Headers

When a request is processed (whether accepted or rejected), the policy adds the following headers to
the response:

- `x-token-limit`: The maximum number of tokens allowed per window for this key

- `x-token-remaining`: The number of tokens remaining in the current window for this key

- `x-token-reset`: The remaining time in milliseconds until the window resets for this key

## Examples

### Basic Configuration

This example limits each authenticated user to 10,000 tokens per minute:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-token-rate-limit
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-token-rate-limit-flex
  config:
    maximumTokens: 10000
    timePeriodInMilliseconds: 60000
    keySelector: "#[attributes.principal]"
```

### Rate Limit by Client ID

This example limits each client to 50,000 tokens per 5 minutes, based on a `ClientId` header:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-token-rate-limit-client
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-token-rate-limit-flex
  config:
    maximumTokens: 50000
    timePeriodInMilliseconds: 300000
    keySelector: "#[attributes.headers['ClientId']]"
```

### Rate Limit by IP Address

This example limits each source IP address to 5,000 tokens per 10 seconds:

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: a2a-v1-token-rate-limit-ip
spec:
  targetRef:
    kind: ApiInstance
    name: my-a2a-v1-agent
  policyRef:
    name: a-two-a-v1-token-rate-limit-flex
  config:
    maximumTokens: 5000
    timePeriodInMilliseconds: 10000
    keySelector: "#[attributes.headers['X-Forwarded-For']]"
```