> ## Documentation Index > Fetch the complete documentation index at: https://docs.brew.new/llms.txt > Use this file to discover all available pages before exploring further. # Response headers > Every header the Brew Public API v1 sets on responses — request correlation, rate limits, idempotency, deprecation, caching. A complete catalog of the headers Brew sets on API responses — what each one means, when it's present, and how to consume it. ## Headers on every response | Header | Example | Notes | | ----------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `x-request-id` | `req_8cac13fd94e6420cacdd75a1aa403a28` | Opaque per-request correlator. **Always include in support tickets** — Brew engineers can trace your call through the full pipeline. | | `Cache-Control` | `no-store` | Brew responses are never cached; integrators should not cache them either. | | `X-RateLimit-Limit` | `100` | Requests allowed in the current rolling 60s window for this route + key. | | `X-RateLimit-Remaining` | `73` | Requests left before the window exhausts. Honor this to preemptively slow down. | | `X-RateLimit-Reset` | `1717891234` | Unix epoch seconds when the window resets. | ## Headers on specific responses | Header | When | Format | | --------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | `Retry-After` | `429 RATE_LIMITED` | Integer seconds. Honor verbatim or take `max(Retry-After, your-backoff)`. | | `X-Credit-Cost` | On a **successful fixed-cost** credit-metered `POST` (e.g. `/v1/content/transform`, `/v1/content/html-to-png`) | Integer credits charged for this call. | | `X-Credits-Remaining` | Alongside `X-Credit-Cost` on a successful fixed-cost call | Integer balance after the charge. | | `Deprecation` | Only on a deprecated alias route — **none are active today** | `true` | | `Sunset` | Only on a deprecated alias route — **none are active today** | RFC 9745 timestamp, e.g. `2026-12-01T00:00:00Z` | | `Link` | Only on a deprecated alias route — **none are active today** | `<…canonical successor URL…>; rel="successor-version"` | **Usage-metered** operations (email generate / edit, image generation) bill the actual model usage and do **not** emit these headers — read your balance from `GET /v1/usage` instead. See [Credits](/api-reference/api/credits) for the full metering model. These deprecation headers are defined for forward-compatibility, but no v1 routes are currently deprecated — you will not see them on any live route today. If a route is ever sunset, the `Link` header will point at its canonical successor. ## Request headers Brew honors Set these on requests when applicable: | Header | Purpose | See | | -------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------- | | `Authorization: Bearer brew_…` | API key authentication (preferred) | [Authentication](/api-reference/api/authentication) | | `X-API-Key: brew_…` | API key authentication (alternative — pick one) | [Authentication](/api-reference/api/authentication) | | `Idempotency-Key: <≤100 chars>` | Replay-safe `POST` retries — same key + same body = cached response for 24h | [Idempotency](/api-reference/api/idempotency) | | `Content-Type: application/json` | Required on `POST` / `PATCH` with a body | | ## Inspecting headers from clients ### `curl` ```bash theme={null} curl -i -H "Authorization: Bearer $BREW_API_KEY" \ https://brew.new/api/v1/audiences ``` `-i` (or `-D -`) prints the response headers above the body. ### TypeScript SDK (raw mode) ```ts theme={null} const { headers, data } = await brew.audiences.list( { limit: 50 }, { raw: true } // returns BrewRawResponse<…> instead of just the body ) console.log(headers.get('x-request-id')) console.log(headers.get('X-RateLimit-Remaining')) ``` Pass `{ raw: true }` in `RequestOptions` on any SDK call to get the full `BrewRawResponse` with the headers. ### `fetch` ```ts theme={null} const res = await fetch('https://brew.new/api/v1/contacts', { headers: { Authorization: `Bearer ${process.env.BREW_API_KEY!}` }, }) console.log(res.headers.get('x-request-id')) console.log(res.headers.get('X-RateLimit-Limit')) console.log(res.headers.get('X-RateLimit-Remaining')) console.log(res.headers.get('X-RateLimit-Reset')) console.log(res.headers.get('Retry-After')) console.log(res.headers.get('Deprecation')) console.log(res.headers.get('Sunset')) console.log(res.headers.get('Link')) ``` ## Header → action mapping A typical agent / SDK consumes these headers like so: | Header | If you see... | Do | | ----------------------- | ------------------- | --------------------------------------------------------------------------------- | | `X-RateLimit-Remaining` | `0` or near `0` | Pause until `X-RateLimit-Reset` to avoid a `429`. | | `Retry-After` | Anything (on `429`) | Sleep that many seconds, then retry with the same `Idempotency-Key`. | | `Deprecation: true` | On a legacy route | Migrate to the URL in the `Link: rel="successor-version"` header before `Sunset`. | | `Sunset` | On a legacy route | Plan the migration; the alias stops working at that timestamp. | | `x-request-id` | Always | Log it; surface it on every customer-facing error. | ## Casing HTTP headers are case-insensitive. Brew emits `x-request-id` lowercase, `X-RateLimit-*` and `Retry-After` in canonical case; `fetch` / SDKs read them case-insensitively. ## See also * [Rate limits](/api-reference/api/rate-limits) — the canonical `429` cookbook. * [Idempotency](/api-reference/api/idempotency) — `Idempotency-Key` semantics. * [Errors](/api-reference/api/errors) — error envelope (the body that pairs with `429 RATE_LIMITED`, `409 IDEMPOTENCY_CONFLICT`, etc.). * [API introduction](/api-reference/api/api-introduction) — the overview that links every reference page. No v1 routes are currently deprecated, so `Deprecation` / `Sunset` / `Link` are not emitted on any live route today. ## Need Help? Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you: Type in the "Ask any question" search bar at the top left to instantly find relevant documentation pages. Click "Open in ChatGPT" at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights. Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions. Need immediate assistance? Reach us at **+1-(332)-203-2145** for urgent issues or time-sensitive questions. Our preferred support channel. You'll receive an invite after signup for direct founder support and fast responses. Contact us at **[support@brew.new](mailto:support@brew.new)** for detailed inquiries or if you prefer not to use Slack.