Why Every Retry Needs Idempotency
A network timeout does not tell a caller whether the server finished aPOST.
Repeating the request can therefore create a second workflow run, send a
second email, or charge for the same generation twice. A stable key lets Brew
recognize the retry and replay the original result without doing the work
again. A changed body must use a new key so a genuine new operation is not
hidden as a retry.
This is why idempotency matters most at boundaries where another system may
redeliver an event or where a long-running request can outlive its connection:
trigger fires, sends, email generation, and batch contact writes. See the
Idempotency reference for the exact window,
conflict response, and key patterns.
Why Batch Writes Allow Partial Success
Rows in an import are independent. Rejecting a 1,000-row request because three addresses are malformed would make callers resend valid work and would hide the rows that need fixing. Brew validates each row, writes the valid rows, and reports the failures beside them so a caller can correct and retry only the bad rows. This keeps the batch endpoint useful for imports while leaving transaction semantics with the caller. If an application needs all-or-nothing behavior, validate and stage the input before calling the endpoint, or use a separate compensating workflow that knows which records it owns. The response does not identify which successful rows were newly inserted, so deleting every address from the input could remove pre-existing contacts. See Batch operations for the response shape and limits.Why Webhooks Complement Polling
Email webhooks push delivery and engagement events to your receiver. Status reads still expose the durable send or run state for reconciliation and recovery if your receiver misses a notification. Automation run completion and other asynchronous jobs use polling. Keep the identifier returned by the accepted operation and follow Async jobs & polling.Related
- Authentication: key lifecycle, scopes, and brand binding.
- Rate limits: per-route policies and
429recovery. - Errors: the standard error envelope and code catalog.
- Credits: credit costs and metering.
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
- Talk to Our Team
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.