Idempotency

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.

​

Contract

​

Why every retry needs it

• POST /v1/automation/runs — fire branch. A doubled fire = doubled welcome / drip / receipt emails.
• POST /v1/sends — EMAIL_ALREADY_SENT (409) blocks a same-email retry; an idempotency key lets a retry return the original runId cleanly.
• POST /v1/emails — generate is expensive (~30–90s). Idempotency makes a flaky-network retry free.
• POST /v1/contacts (single OR batch) — the underlying upsert is naturally idempotent on email, but Idempotency-Key saves you the second batch run.

​

Body-field fallback on the fire branch

{
  "triggerEventId": "tri_signup",
  "payload": { "email": "jane@example.com", "firstName": "Jane" },
  "idempotencyKey": "signup-jane@example.com-1779292800"
}

​

Recommended key patterns

• <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}`

async function fireWithRetry() {
  for (let attempt = 0; attempt < 5; attempt += 1) {
    const res = await fetch('https://brew.new/api/v1/automation/runs', {
      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({
        triggerEventId: 'tri_signup',
        payload: { email: 'jane@example.com', firstName: 'Jane' },
      }),
    })
    if (res.ok) return res.json()
    if (res.status === 409) {
      const body = await res.json()
      if (body.error?.code === 'IDEMPOTENCY_CONFLICT') {
        // You changed the body between retries. Fix the body OR mint a fresh key.
        throw new Error('Idempotency conflict — fix the body or use a new key')
      }
    }
    if (res.status === 429) {
      const wait = Number(res.headers.get('Retry-After') ?? '1') * 1000
      await new Promise((r) => setTimeout(r, wait))
      continue
    }
    if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`)
  }
  throw new Error('Exhausted retries')
}

1. Reuse the same idempotencyKey across every retry of the same logical operation. The first request wins; the rest return the cached response.
2. Mint a fresh idempotencyKey when the body genuinely changes. A new email recipient = a new key.

​

409 IDEMPOTENCY_CONFLICT envelope

{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "type": "conflict",
    "message": "Idempotency-Key 'signup-jane@example.com-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"
  }
}

​

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.
• Workflow runs — POST /v1/automation/runs fire creates rows in automationExecutions. An idempotent replay returns the original automationRunIds[] under details so polling stays consistent.
• Sends — POST /v1/sends reserves the email atomically via reserveEmailSend. An idempotent replay short-circuits before re-reservation; a fresh key on a same-email send produces 409 EMAIL_ALREADY_SENT.

​

SDK behaviour

await brew.automationRuns.fire(
  {
    triggerEventId: 'tri_signup',
    payload: { email: 'jane@example.com' },
  },
  { idempotencyKey: `signup-${userId}-${eventTimestamp}` }
)

​

See also

• 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?