# Super API rate limits and response headers

Every live Super 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.

## Response fields

- `RateLimit-Policy` publishes the active policy name, request quota, and window in seconds using Structured Field syntax.
- `RateLimit` publishes the active policy name, remaining requests, and seconds until reset.
- `RateLimit-Limit` publishes the enforced request quota for compatibility clients.
- `RateLimit-Remaining` publishes the remaining requests for compatibility clients.
- `RateLimit-Reset` publishes seconds until reset for compatibility clients.
- `Retry-After` is present on an HTTP 429 response and gives the minimum delay before retrying.
- `X-Request-Id` identifies the request when contacting SuperPowers AI support.

The combined fields follow the current IETF HTTPAPI rate-limit header draft. The individual `RateLimit-*` fields are provided for compatibility with clients that have not adopted the combined format.

## Example

```http
RateLimit-Policy: "ip";q=1800;w=60
RateLimit: "ip";r=1799;t=60
RateLimit-Limit: 1800
RateLimit-Remaining: 1799
RateLimit-Reset: 60
```

The first field declares a quota of 1,800 requests in a 60-second IP window. The second reports 1,799 requests remaining and 60 seconds until the active window resets.

## Multiple policies

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 instead of assuming a fixed quota across every route.

## HTTP 429 handling

Honor `Retry-After` before retrying. Preserve idempotency keys for payment and mutation requests, add bounded jitter, and retry only the operation that was rejected. Continued HTTP 429 responses should extend the backoff rather than creating parallel retries.

The rate-limit fields, `Retry-After`, and `X-Request-Id` are exposed through CORS for browser clients. Machine-readable definitions are published in https://getsupers.com/openapi.json.