Current structured fields
RateLimit-Policy publishes quota and window. RateLimit publishes remaining requests and reset seconds using Structured Field syntax.
Super API rate limits and response headers
Every live API response tells agents which quota is active, how many requests remain, and when the current window resets. When a request is rejected with HTTP 429, Super also returns Retry-After so clients can pause instead of retrying blindly.
Compatibility fields
RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset carry the same enforced values for clients that have not adopted the combined fields.
Rejected requests
HTTP 429 responses include Retry-After. Wait for at least that many seconds, then retry once with normal backoff and jitter.
Read the enforced quota
Header values come from the same sliding windows that accept or reject each request.
Example success fields
RateLimit-Policy: "ip";q=1800;w=60 declares a quota of 1,800 requests in a 60-second IP window. RateLimit: "ip";r=1799;t=60 reports 1,799 requests remaining and 60 seconds until the active window resets.
Authentication endpoints
OAuth and other authentication-sensitive routes may advertise the stricter auth-ip policy. Short bursts may advertise ip-burst. Clients must read the policy name and values on each response rather than assuming one fixed quota across every route.
HTTP 429 handling
Do not immediately replay a rejected operation. Honor Retry-After, preserve idempotency keys for payment or mutation requests, and add bounded jitter before retrying. Continued HTTP 429 responses should extend the backoff rather than creating parallel retries.
Browser access
The rate-limit fields, Retry-After, and X-Request-Id are listed in Access-Control-Expose-Headers, so browser-based developer tools can read them. The OpenAPI document defines the same fields for machine-readable client generation.
Let the response set the pace.
Read the current quota, keep mutation retries idempotent, and honor Retry-After whenever Super returns HTTP 429.