Idempotency

Reuse stable idempotency keys for supported Brew API writes. Learn the replay windows, conflict handling, and safe retry key patterns.

Supported POST endpoints use the Idempotency-Key HTTP header. Most writes replay the cached response for 24 hours; trigger fires replay for 90 days. The same key with a different body returns 409 IDEMPOTENCY_CONFLICT.

A key is shared by the HTTP API and MCP. A write retried over the other interface with the same inputs and key replays its first result.

One replay can look different from a normal HTTP result. When an MCP create_email call outlasts its wait, it returns status: "generating", emailId, and runId. An HTTP retry of POST /v1/emails with the same key replays the accepted result instead of generating a second design.

Poll GET /v1/emails/{emailId}?runId={runId} until the design is ready or failed.

Contract

Property	Value
Header	Idempotency-Key: <≤ 100 chars>
Methods	Supported POST endpoints. Check the endpoint schema; image-upload handshakes do not support replay.
Window	24 hours from the first request. A trigger fire key lasts as long as the fire’s receipt: 90 days.
Same key + same body	Returns the original cached response (same status, same body, same headers). A trigger fire is the one exception.
Same key + different body	409 IDEMPOTENCY_CONFLICT. The same body on another resource of the route, such as a different id in the path, conflicts the same way.
Different key	Treated as a fresh request.
Scope	Namespaced per organization, brand, and operation, with the request’s path ids part of what the key is bound to. One tenant’s key cannot collide with another’s.
Surfaces	Shared by HTTP and MCP. Idempotency-Key and the MCP idempotency_key argument are the same key.

Why Every Retry Needs It

Stable keys prevent duplicate work when a network error or event redelivery makes a caller repeat a POST. See API design notes for the rationale and this page’s contract for the exact behavior.

In-Progress Requests and Storage Outages

For writes using the response cache, a running request holds its key for up to 15 minutes. A retry during that time returns 409 IDEMPOTENCY_IN_PROGRESS. Wait, then replay with the same inputs and key.

Replay guarantees depend on the idempotency store. If that store is unavailable, six writes fail closed. They return a retryable 503 SERVICE_UNAVAILABLE with a Retry-After header:

• POST /v1/sends
• POST /v1/emails/audit
• POST /v1/emails/{emailId}/inbox-placement-tests
• POST /v1/automations/{automationId}/test
• POST /v1/automations/{automationId}/run
• POST /v1/automations/triggers/{triggerEventId}/fire

Other writes using it can run without deduplication.

For another write that must never repeat, disable automatic retries and check whether the first request succeeded before retrying.

Replayed Trigger Fires

POST /v1/automations/triggers/{triggerEventId}/fire says when a response is a replay. The first fire answers 202 with status: "triggered". A repeat answers 200 with status: "replayed" and the original triggerInstanceId and automationRunIds.

No new runs start. The MCP fire_trigger_event tool reports a replay the same way.

A fire key is matched against the stored trigger receipt and keeps replaying for its 90-day retention period. Use one key per business action and never reuse a key for a different fire.

The fire takes its key only from the Idempotency-Key header. A body idempotencyKey field is rejected with 400 INVALID_REQUEST.

Recommended Key Patterns

The key MUST be stable per logical operation. Common recipes:

Operation	Recommended key
Trigger fire from a webhook	<eventName>-<userId>-<eventTimestamp> (for example signup-user_123-1779292800)
Trigger fire from an internal job	<jobName>-<runId>-<targetUserId>
Campaign send	send-<emailId>-<audienceId>-<scheduledAt or "now">
Email generate from a chat	email-gen-<conversationId>-<turnId>
Batch contact upsert	contacts-batch-<importId>
Cron-driven daily blast	daily-promo-<YYYY-MM-DD>

Anti-patterns to avoid:

• <uuid()> per call: defeats the purpose; every retry gets a fresh key.
• Date.now() per call: same as above.
• <sha256(body)>: vulnerable to partial replays where body bytes change.

Worked Example: Fire a Trigger with Retry

const idempotencyKey = `signup-${userId}-${eventTimestamp}`

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))

async function fireWithRetry() {
  for (let attempt = 0; attempt < 5; attempt += 1) {
    let res: Response
    try {
      res = await fetch('https://brew.new/api/v1/automations/triggers/tri_signup/fire', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.BREW_API_KEY!}`,
          'Content-Type': 'application/json',
          // Same key on every attempt, first one wins, the rest replay
          'Idempotency-Key': idempotencyKey,
        },
        body: JSON.stringify({
          payload: { email: '[e-mail]', firstName: 'Jane' },
        }),
      })
    } catch {
      // Network error: the outcome is unknown, so retry with the same key
      await sleep(1000 * 2 ** attempt)
      continue
    }
    if (res.ok) return res.json()
    if (res.status === 429) {
      await sleep(Number(res.headers.get('Retry-After') ?? '1') * 1000)
      continue
    }
    const body = await res.json().catch(() => null)
    if (res.status === 409 && body?.error?.code === 'IDEMPOTENCY_IN_PROGRESS') {
      // The first attempt is still running: wait, then replay with the same key
      await sleep(1000 * 2 ** attempt)
      continue
    }
    throw new Error(`HTTP ${res.status}: ${JSON.stringify(body)}`)
  }
  throw new Error('Exhausted retries')
}

Two invariants:

1. Reuse the same idempotencyKey across every retry of the same logical operation. The first request wins; later attempts replay its result.
2. Mint a fresh idempotencyKey when the body changes. A new email recipient = a new key.

409 IDEMPOTENCY_CONFLICT Envelope

{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "type": "conflict",
    "message": "Idempotency-Key '[e-mail]-1779292800' was previously used with a different request body.",
    "suggestion": "Use a fresh key OR submit the exact same body as the original request.",
    "docs": "https://docs.brew.new/api-reference/api/idempotency"
  }
}

The cached original response can be re-fetched by replaying with the same body. There is no separate “get cached result” endpoint.

Where It Interacts with Other Contracts

• Rate limits: an idempotent replay counts against the rate-limit window. If you saw a 429 on the first attempt, the retry will hit the gate too. Honor Retry-After, don’t burn keys. A 429 isn’t stored under the key, so the same key works once the window clears.
• Workflow runs: a trigger replay returns the original automationRunIds[] at the top level, so polling follows the same runs.
• Sends: a production-send replay returns the original sendId. A fresh key creates another send of the design.

SDK Behavior

The official @brew.new/sdk generates a key for each supported POST operation and retains it across automatic retries. Image-upload steps have separate retry rules. To recover across processes, supply and retain a stable key in RequestOptions:

await brew.automations.triggers.fire(
  {
    triggerEventId: 'tri_signup',
    payload: { email: '[e-mail]' },
  },
  { idempotencyKey: `signup-${userId}-${eventTimestamp}` }
)

Related

• Rate limits: pair with idempotency for safe retry loops.
• Errors: full 409 IDEMPOTENCY_CONFLICT envelope.
• Async jobs & polling: for fire / send retries you typically don’t need to call again. Poll the run instead.

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:

Self-Service Tools

Search Documentation

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

Ask ChatGPT or Claude

Click here to open the Copy page menu at the top of this page, then send the page to ChatGPT, Claude, or your editor.

Talk to Our Team

Schedule a Call

Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.

Call Us Directly

Need immediate assistance? Reach us at [phone] for urgent issues or time-sensitive questions.

Slack Channel

Our preferred support channel. You’ll receive an invite after signup for direct founder support and fast responses.

Email Support

Contact us at [e-mail] for detailed inquiries or if you prefer not to use Slack.