Rate Limits

​

Headers

​

Per-Route Policies

​

Session Traffic: 300/min Ceiling

​

Generosity & Burst Behavior

• The window is a rolling 60 seconds, not a fixed wall-clock minute. A spike at the top of a minute does NOT get a free second budget.
• The store uses Redis sorted-sets (when available); when Redis is unavailable, every rate-limited endpoint fails open with X-RateLimit-Remaining: <limit> and X-RateLimit-Reset: now+60. You will not see spurious 429s during a Redis blip.
• Test mode bypass: BREW_DISABLE_API_RATE_LIMIT=1 on the dev server skips the gate entirely (test-only env var; never set in production).

​

429 Recovery Cookbook

import { setTimeout as sleep } from 'node:timers/promises'

async function withRetry<T>(fn: () => Promise<Response>): Promise<T> {
  for (let attempt = 0; attempt < 5; attempt += 1) {
    const res = await fn()
    if (res.status !== 429) {
      if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`)
      return (await res.json()) as T
    }
    const retryAfterSec = Number(res.headers.get('Retry-After') ?? '1')
    const backoffSec = Math.max(retryAfterSec, 2 ** attempt)
    await sleep(backoffSec * 1000)
  }
  throw new Error('Exhausted retries after repeated 429 responses')
}

// Create one stable key per logical send, outside the retry callback.
const idempotencyKey = 'send-promo-2026-11-27'

const sendResponse = await withRetry<{ status: string; runId: string }>(() =>
  fetch('https://brew.new/api/v1/sends', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.BREW_API_KEY!}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify({
      emailId: 'eml_abc',
      domainId: 'dom_brand_primary',
      audienceId: 'aud_subscribers',
      subject: 'Black Friday, 40% off',
    }),
  })
)

• Always honor Retry-After. Take the max of Retry-After and your own back-off so you don’t out-aggressive yourself.
• Reuse the same Idempotency-Key on every retry. See Idempotency for replay semantics.
• Preemptively pause when X-RateLimit-Remaining hits 0. The header ships on rate-limited responses, so a well-behaved client can throttle itself before a 429 ever fires.

​

Server-Side Observability

​

See Also

• Idempotency: pair with Idempotency-Key so retries are safe.
• Errors: full error envelope + every error.code.
• Response headers: every header Brew sets.
• Async jobs & polling: for POST /v1/sends and POST /v1/automations/triggers/{triggerEventId}/fire, you don’t need to call the API again to wait for delivery. Poll the run.

​

Need Help?