Announce the remaining quota before the agent hits the limit

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 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/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.