# AX-SYS-37: Announce the remaining quota before the agent hits the limit

> Notifications and change · intermediate · AX-SYS-37

Report the caller's remaining quota and the time window it covers on every response, not only on the 429, so an agent can slow down before it is throttled.

## Why

An agent working through a backlog, such as 300 refunds, has no built-in sense of pace. If the only signal is a 429 after the limit is gone, it learns the limit by hitting it, and the batch fails halfway with some refunds done and some not. HTTP already has a way to say how long to wait: RFC 9110's `Retry-After` tells the client how long it ought to wait before making a follow-up request. That arrives only after the failure. The IETF HTTPAPI working group's RateLimit header fields draft (`draft-ietf-httpapi-ratelimit-headers-11`, May 2026, intended for Standards Track) moves the signal earlier: `RateLimit-Policy` advertises the quota policy and `RateLimit` the quota still available, which lets clients avoid being throttled at all. GitHub's REST API already sends this on ordinary responses (`x-ratelimit-limit`, `-remaining`, `-used`, `-reset`, `-resource`) and tells clients to use those headers to pace and back off, without relying on an exact remaining count, and to wait out `retry-after` when it is present. [AX-SYS-21](ax-sys-21-bound-autonomy-with-limits.mdx) decides what the cap is; this principle tells the agent where it stands against that cap while there is still time to adjust.

## Do

Send the policy and the remaining quota with its time window on every response, and add `Retry-After` whenever you do throttle.

## Don't

Keep limits hidden until the first 429, or return a 429 that gives no hint of when to try again.

## Artifact

```http
HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Policy: "refunds";q=100;w=60
RateLimit: "refunds";r=4;t=38

HTTP/1.1 429 Too Many Requests
RateLimit: "refunds";r=0;t=21
Retry-After: 21
```

With 4 refunds available for the next 38 seconds, the agent spaces out its next calls instead of firing them all and failing on the fifth.

## Citations

1. [IETF draft-ietf-httpapi-ratelimit-headers-11: RateLimit header fields for HTTP](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/): Defines the RateLimit-Policy and RateLimit HTTP header fields for servers to advertise their quota policies and the current service limits, thereby allowing clients to avoid being throttled (Internet-Draft, intended status Standards Track, May 2026)
2. [GitHub Docs: Rate limits for the REST API](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api): Responses carry x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used, x-ratelimit-reset and x-ratelimit-resource; clients should use the x-ratelimit-* headers to pace and back off requests but avoid logic that depends on an exact remaining count, and if a retry-after header is present, not retry until that many seconds have elapsed
3. [RFC 9110: HTTP Semantics (10.2.3, Retry-After)](https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after): Servers send the Retry-After header field to indicate how long the user agent ought to wait before making a follow-up request

---
Source: Agent Experience Principles (axprinciples.com)