Skip to main content
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

HeaderExampleNotes
x-request-idreq_8cac13fd94e6420cacdd75a1aa403a28Opaque per-request correlator. Always include in support tickets — Brew engineers can trace your call through the full pipeline.
Cache-Controlno-storeBrew responses are never cached; integrators should not cache them either.
X-RateLimit-Limit100Requests allowed in the current rolling 60s window for this route + key.
X-RateLimit-Remaining73Requests left before the window exhausts. Honor this to preemptively slow down.
X-RateLimit-Reset1717891234Unix epoch seconds when the window resets.

​
Headers on specific responses

HeaderWhenFormat
Retry-After429 RATE_LIMITEDInteger seconds. Honor verbatim or take max(Retry-After, your-backoff).
X-Credit-CostOn 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-RemainingAlongside X-Credit-Cost on a successful fixed-cost callInteger balance after the charge.
DeprecationOnly on a deprecated alias route — none are active todaytrue
SunsetOnly on a deprecated alias route — none are active todayRFC 9745 timestamp, e.g. 2026-12-01T00:00:00Z
LinkOnly 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 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:
HeaderPurposeSee
Authorization: Bearer brew_…API key authentication (preferred)Authentication
X-API-Key: brew_…API key authentication (alternative — pick one)Authentication
Idempotency-Key: <≤100 chars>Replay-safe POST retries — same key + same body = cached response for 24hIdempotency
Content-Type: application/jsonRequired on POST / PATCH with a body

​
Inspecting headers from clients

​
curl

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)

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<T> with the headers.

​
fetch

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:
HeaderIf you see…Do
X-RateLimit-Remaining0 or near 0Pause until X-RateLimit-Reset to avoid a 429.
Retry-AfterAnything (on 429)Sleep that many seconds, then retry with the same Idempotency-Key.
Deprecation: trueOn a legacy routeMigrate to the URL in the Link: rel="successor-version" header before Sunset.
SunsetOn a legacy routePlan the migration; the alias stops working at that timestamp.
x-request-idAlwaysLog 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 — the canonical 429 cookbook.
  • Idempotency — Idempotency-Key semantics.
  • Errors — error envelope (the body that pairs with 429 RATE_LIMITED, 409 IDEMPOTENCY_CONFLICT, etc.).
  • 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:

Search Documentation

Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.

ChatGPT/Claude Integration

Click “Open in ChatGPT” at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights.