Skip to main content
Reference pages define the Brew API contract. These notes explain the choices behind a few cross-cutting behaviors so you can make better decisions when building around that contract.

​
Why Every Retry Needs Idempotency

A network timeout does not tell a caller whether the server finished a POST. 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 Polling Before Outbound Webhooks

The API has asynchronous work today, but outbound webhooks are not shipped yet. Polling is the supported pattern because every accepted operation returns a durable run or send identifier, and the status reads already expose the same state the dashboard uses. That gives backends a predictable integration without asking them to implement a delivery protocol that is still changing. When outbound webhooks arrive, they can add push delivery for systems that need it. They will still complement, rather than replace, status reads for reconciliation and recovery. Until then, use Async jobs & polling and follow the planned status in Events & webhooks.

​
See Also

  • Authentication: key lifecycle, scopes, and brand binding.
  • Rate limits: per-route policies and 429 recovery.
  • 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:

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 explore it further with ChatGPT or Claude.