Errors

Most non-2xx responses from the Brew Public API v1 return the standard JSON error envelope. The trigger-fire endpoint keeps a legacy fire envelope for 400 PAYLOAD_MISMATCH; branch on the stable code or status field, not on a human-readable message that can change.

The Error Envelope

{
  "error": {
    "code": "AUTOMATION_GRAPH_INVALID",
    "type": "invalid_request",
    "message": "\"Welcome\" references emailVersionId 'emv_xxx' which does not exist in this brand. (and 1 more graph issue)",
    "param": "nodes[0].config.emailVersionId",
    "suggestion": "Fix every issue reported in `details.issues` then resubmit.",
    "docs": "https://docs.brew.new/api-reference/api/errors",
    "retryAfter": 12,
    "details": { "issues": [/* ... */] }
  }
}

Field	Type	When set
`code`	string	Always. Stable identifier: branch SDK logic on this.
`type`	enum	Always. One of `authentication_error \| authorization_error \| invalid_request \| not_found \| conflict \| rate_limit \| payment_required \| service_unavailable \| not_implemented \| internal_error`.
`message`	string	Always. Human-readable summary. Can change.
`param`	string?	When the failing field is known (e.g. `payloadSchema.fields`, `nodes[0].config.emailVersionId`).
`suggestion`	string	Always. Concrete recovery hint.
`docs`	string	Always. Deep-link to canonical reference.
`retryAfter`	int?	On retryable `429` or `503` responses. Mirrors the `Retry-After` header (seconds).
`details`	object?	Machine-readable extras (e.g. `details.blockers[]`, `details.issues[]`).

Every code on this page has a stable anchor at #<code-in-kebab-case>, so INSUFFICIENT_CREDITS is addressable as /api-reference/api/errors#insufficient-credits. Link those anchors from support threads, runbooks, and agent prompts. Today the envelope’s docs value is the page URL; appending the per-code fragment on the API side is an open question tracked in the repo notes.

`details` Shape: `PUBLISH_VALIDATION_FAILED` (409)

When PATCH /v1/automations/{automationId} with { published: true } is blocked, details.blockers[] enumerates every node-level reason so callers can render a fix-it list.

{
  "error": {
    "code": "PUBLISH_VALIDATION_FAILED",
    "type": "conflict",
    "message": "Add at least one Send Email action",
    "details": {
      "blockers": [
        { "nodeId": "send_1", "nodeLabel": "Welcome", "severity": "error", "message": "\"Welcome\" is missing an inbox preview" }
      ]
    }
  }
}

`details` Shape: `AUTOMATION_GRAPH_INVALID` (400)

When POST /v1/automations (or PATCH with new nodes/connections) fails the server-side FK + structural resolver, details.issues[] enumerates every problem. Each carries a kind you can branch on:

{
  "error": {
    "code": "AUTOMATION_GRAPH_INVALID",
    "type": "invalid_request",
    "details": {
      "issues": [
        { "kind": "email_wrong_type", "nodeId": "send_welcome", "message": "Referenced email is campaign — must be automation or transactional." },
        { "kind": "domain_not_ready", "nodeId": "send_welcome", "message": "Domain not verified for sending." }
      ]
    }
  }
}

`kind`	Cause
`duplicate_node_id`	Two nodes share the same `id`.
`connection_unknown_from`	`connection.from` points to a non-existent node.
`connection_unknown_to`	`connection.to` points to a non-existent node.
`connection_targets_trigger`	A connection targets the trigger node (triggers are entry-only).
`connection_self_loop`	`connection.from === connection.to`.
`email_not_found`	`emailVersionId` doesn’t exist in this brand.
`email_version_mismatch`	`emailVersionId` exists but belongs to a different `emailId`.
`email_wrong_type`	Referenced email is `campaign`: must be `automation` or `transactional`.
`domain_not_found`	`domainId` doesn’t exist in this brand.
`domain_not_ready`	Domain not verified for sending.

Foundational Error Codes (Every Endpoint)

These can appear on any v1 endpoint:

Code	HTTP	`type`	Recovery
`AUTHENTICATION_REQUIRED`	401	`authentication_error`	Set the `Authorization: Bearer <key>` (or `X-API-Key: <key>`) header.
`INVALID_API_KEY`	401	`authentication_error`	The key is malformed or unknown. Re-issue at brew.new/settings/api.
`API_KEY_REVOKED`	401	`authentication_error`	The key was revoked. Re-issue.
`INSUFFICIENT_PERMISSIONS`	403	`authorization_error`	The key lacks the route’s permission scope. `error.param` carries the missing scope name.
`METHOD_NOT_ALLOWED`	405	`invalid_request`	Wrong verb on this resource.
`INVALID_REQUEST`	400	`invalid_request`	Zod failure / unknown body key / malformed JSON / sending a removed field (e.g. `provider` on `POST /v1/automations/triggers`). Fix the body per `error.param`.
`IDEMPOTENCY_CONFLICT`	409	`conflict`	Same `Idempotency-Key` reused with a different body. Use a fresh key OR don’t change the body. See Idempotency.
`RATE_LIMITED`	429	`rate_limit`	Back off using `Retry-After`. See Rate limits.
`NOT_IMPLEMENTED`	501	`not_implemented`	The endpoint stub is wired but the feature isn’t shipped yet.
`INTERNAL_ERROR`	500	`internal_error`	Unhandled server error. Include the `x-request-id` from the response when contacting support.

Resource-Specific Codes

Triggers (`/v1/automations/triggers`)

Code	HTTP	Recovery
`TRIGGER_EVENT_NOT_FOUND`	404	List with `GET /v1/automations/triggers` to find the id.
`TRIGGER_IMMUTABLE`	422	Integration trigger (Clerk / Stripe / …): managed from the integration card on the Brew dashboard; the public API doesn’t accept metadata edits to it. Connecting the integration provisions every supported event automatically; whether each event fires is controlled by which automations are published.
`TRIGGER_HAS_DEPENDENT_AUTOMATIONS`	409	Delete/detach the automations first. `details.referencingAutomations[]` lists each `{ automationId, name, published }`.
`PAYLOAD_SCHEMA_EMAIL_REQUIRED`	400	Add `{ key: 'email', type: 'string', required: true }` to `payloadSchema.fields`. The email field is the contact key downstream automations route on.
`PAYLOAD_MISMATCH`	400 fire envelope	The trigger payload did not satisfy its schema. The response carries `success: false`; fix the missing or invalid field and fire again.

Automations (`/v1/automations`)

Code	HTTP	Recovery
`AUTOMATION_NOT_FOUND`	404	List with `GET /v1/automations`.
`AUTOMATION_VERSION_NOT_FOUND`	404	Drop `automationVersionId` or use a known one (returned by `GET /v1/automations?automationId=…&include=versions`).
`AUTOMATION_NOT_PUBLISHED`	422	Publish first before unpublishing.
`AUTOMATION_GRAPH_INVALID`	400	Iterate over `details.issues` and fix each one. See the issue-kind table above.
`PUBLISH_VALIDATION_FAILED`	409	Iterate over `details.blockers[]`; each carries `nodeId`, `nodeLabel`, `message`.

Automation Runs (`/v1/automations/runs`)

Code	HTTP	Recovery
`NO_PUBLISHED_AUTOMATION`	422	At least one automation attached to the trigger must be `published: true` before a fire can match.
`AUTOMATION_RUN_NOT_FOUND`	404	List with `GET /v1/automations/runs` (paginated).
`RUN_NOT_PAUSABLE`	409	The audience run is not in a state that supports the requested pause, resume, or cancel action. Read the run first.
`NOT_FOUND`	404	The requested audience run does not exist for this brand. List with `GET /v1/automations/audience-runs`.

Emails (`/v1/emails`)

Code	HTTP	Recovery
`EMAIL_NOT_FOUND`	404	List with `GET /v1/emails`.
`EMAIL_VERSION_NOT_FOUND`	404	Drop `emailVersionId` or fetch a valid one.
`EMAIL_NOT_READY`	422	The email row’s `status !== 'complete'`: the agent is still generating. Wait and retry.
`EMAIL_IN_PROGRESS`	409	The email is currently `status: 'streaming'` (another `PATCH /v1/emails/{emailId}` is mid-flight). Wait and retry.
`EMAIL_IMPORT_FAILED`	422	The supplied HTML, MJML, or JSX could not be rendered as an email. Fix `content` for the declared `format` and retry.
`FIGMA_URL_INVALID`	400	The Figma URL is missing a frame reference. Copy a link that includes the selected frame’s `node-id`.
`FIGMA_ACCESS_DENIED`	403	The connected Figma account cannot access the file or frame. Grant access, then retry.
`FIGMA_FRAME_NOT_FOUND`	404	Figma could not find the file or selected frame. Copy a fresh frame link.
`FIGMA_NOT_CONNECTED`	422	Connect or reconnect Figma for the API key’s brand in Brew Integrations.
`FIGMA_CONVERSION_FAILED`	422	The selected frame could not be converted into an email design. Check the frame, then retry. `details.emailId` may carry the partial design.
`FIGMA_UNAVAILABLE`	503	Figma is temporarily unavailable. Retry after `Retry-After`.
`INTEGRATION_NOT_CONNECTED`	400	Connect the requested export provider for this brand, then retry.
`EXPORT_PROVIDER_ERROR`	502	The export provider rejected the request. Check the connection and retry or reconnect it.
`CONTENT_OPERATION_FAILED`	422	The requested audit, preview, placement, or media operation could not complete. Follow `suggestion` and retry when the design is ready.
`BRAND_NOT_FOUND`	404	The API key’s brand was deleted. Re-issue the key.
`BRAND_NOT_READY`	422	Brand extraction (logo / theme / domain) hasn’t finished yet. Wait a few seconds and retry.

Sends (`/v1/sends`)

Code	HTTP	Recovery
`SEND_NOT_FOUND`	404	No send exists for that `sendId` on `GET /v1/analytics/sends?sendId=…`. List with `GET /v1/analytics/sends`.
`DOMAIN_NOT_FOUND`	404	List with `GET /v1/domains`.
`DOMAIN_NOT_READY`	422	The domain isn’t verified for sending. Finish DNS verification in the dashboard.
`AUDIENCE_NOT_FOUND`	404	List with `GET /v1/audiences`. Provide an `audienceId` or inline `to` on `POST /v1/sends`.
`SEND_NOT_CANCELLABLE`	409	The send is already terminal or is an automation send. Read its status before canceling.
`SEND_NOT_PAUSABLE`	409	Only a `sending` gradual send can be paused. Read the send status, then retry when it is eligible.
`SEND_NOT_RESUMABLE`	409	Only a paused gradual send can be resumed. Read the send status, then retry when it is eligible.

Credits and Billing

Code	HTTP	Recovery
`INSUFFICIENT_CREDITS`	402	The balance is below the fixed cost or empty for a usage-metered call. Read `GET /v1/usage`, then top up or upgrade. `details` carries `{ cost, remaining, planKey }`.
`SERVICE_UNAVAILABLE`	503	A required backend check could not complete. Retry after the `Retry-After` duration; calls that produce no result are not billed.

Domains Lifecycle (`/v1/domains`)

Code	HTTP	Recovery
`DOMAIN_ALREADY_EXISTS`	409	The domain already exists for this brand: fetch it via `GET /v1/domains`.
`DOMAIN_VERIFIED_ELSEWHERE`	409	Verified in another workspace; only unverified domains can be reclaimed.
`DOMAIN_OTHER_BRAND`	409	Attached to a different brand in this workspace. Use that brand’s key or remove it first.
`DOMAIN_VERIFICATION_FAILED`	422	`PATCH { domainId, verify: true }` couldn’t verify. Publish the DNS `records` from the row, then retry.
`DOMAIN_PROVIDER_ERROR`	422	The sending provider rejected the domain (e.g. not a registrable name). Fix `name` and retry.

Audiences (`/v1/audiences`)

Code	HTTP	Recovery
`AUDIENCE_NOT_FOUND`	404	Unknown / cross-brand `audienceId`. List with `GET /v1/audiences`.

Contacts + Fields (`/v1/contacts`, `/v1/fields`)

Code	HTTP	Recovery
`CONTACT_NOT_FOUND`	404	Upsert the contact first via `POST /v1/contacts`.
`CORE_FIELD_IMMUTABLE`	422	Don’t write read-only columns (e.g. `createdAt`, `email`).
`FIELD_NOT_FOUND`	404	Create the field first via `POST /v1/fields { fieldName, fieldType }`.
`MISSING_EMAIL`	422	The single-row contact body requires `email`.
`INVALID_EMAIL`	row-level	A contact row contains an invalid address. Fix the row and resubmit it.
`DUPLICATE_EMAILS_IN_BATCH`	row-level	A batch contains the same address more than once. Keep one row per email and retry.
`FIELD_TYPE_MISMATCH`	409	A custom-field value does not match the existing field definition. Coerce the value or update the definition first.

Analytics (`/v1/analytics/trigger-instances`)

Code	HTTP	Recovery
`EVENT_NOT_FOUND`	404	No fired event exists with that id. List with `GET /v1/analytics/trigger-instances`.

Chat Context (`/v1/chats/{chatId}`)

Code	HTTP	Recovery
`CHAT_NOT_FOUND`	404	The chat id is unknown or belongs to another brand. Check the id and use a key bound to the chat’s brand.

SDK Error Handling (TypeScript)

The official @brew.new/sdk throws a typed BrewApiError on every non-2xx response, exposing the full envelope:

import { BrewApiError, createBrewClient } from '@brew.new/sdk'

const brew = createBrewClient({ apiKey: process.env.BREW_API_KEY! })

try {
  await brew.automations.triggers.fire({
    triggerEventId: 'tri_signup',
    payload: { email: 'jane@example.com' },
    idempotencyKey: `signup-${userId}-${eventTimestamp}`,
  })
} catch (err) {
  if (err instanceof BrewApiError) {
    console.error('Brew error', {
      code: err.code,                 // 'TRIGGER_EVENT_NOT_FOUND' etc.
      type: err.type,                 // 'not_found'
      message: err.message,
      requestId: err.requestId,       // include in support tickets
      param: err.param,
      suggestion: err.suggestion,
      docs: err.docs,
      retryAfter: err.retryAfter,
    })

    if (err.code === 'RATE_LIMITED') {
      // back off, then retry
    }
    if (err.code === 'AUTOMATION_GRAPH_INVALID') {
      for (const issue of err.details?.issues ?? []) {
        console.error(`  ${issue.kind} on ${issue.nodeId}: ${issue.message}`)
      }
    }
  }
  throw err
}

Branching Agent / SDK Logic on `code`

Three rules:

code is stable. It’s part of our public contract. We will not change the spelling of a code; we may add new ones.
type is a coarse bucket for default UX. Use type === 'rate_limit' to gate a retry; use type === 'authentication_error' to ask the user to re-issue the key.
Never branch on message. Operator-facing copy may change between releases.

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.

ChatGPT/Claude Integration

Click “Open in ChatGPT” at the top right of any page to explore it further with ChatGPT or Claude.

Get started

Overview

Core concepts

Guides

MCP server

CLI

Public API v1

The Error Envelope

`details` Shape: `PUBLISH_VALIDATION_FAILED` (409)

`details` Shape: `AUTOMATION_GRAPH_INVALID` (400)

Foundational Error Codes (Every Endpoint)

Resource-Specific Codes

Triggers (`/v1/automations/triggers`)

Automations (`/v1/automations`)

Automation Runs (`/v1/automations/runs`)

Emails (`/v1/emails`)

Sends (`/v1/sends`)

Credits and Billing

Domains Lifecycle (`/v1/domains`)

Audiences (`/v1/audiences`)

Contacts + Fields (`/v1/contacts`, `/v1/fields`)

Analytics (`/v1/analytics/trigger-instances`)

Chat Context (`/v1/chats/{chatId}`)

SDK Error Handling (TypeScript)

Branching Agent / SDK Logic on `code`

See Also

Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Email Support

​The Error Envelope

​details Shape: PUBLISH_VALIDATION_FAILED (409)

​details Shape: AUTOMATION_GRAPH_INVALID (400)

​Foundational Error Codes (Every Endpoint)

​Resource-Specific Codes

​Triggers (/v1/automations/triggers)

​Automations (/v1/automations)

​Automation Runs (/v1/automations/runs)

​Emails (/v1/emails)

​Sends (/v1/sends)

​Credits and Billing

​Domains Lifecycle (/v1/domains)

​Audiences (/v1/audiences)

​Contacts + Fields (/v1/contacts, /v1/fields)

​Analytics (/v1/analytics/trigger-instances)

​Chat Context (/v1/chats/{chatId})

​SDK Error Handling (TypeScript)

​Branching Agent / SDK Logic on code

​See Also

​Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Email Support

The Error Envelope

`details` Shape: `PUBLISH_VALIDATION_FAILED` (409)

`details` Shape: `AUTOMATION_GRAPH_INVALID` (400)

Foundational Error Codes (Every Endpoint)

Resource-Specific Codes

Triggers (`/v1/automations/triggers`)

Automations (`/v1/automations`)

Automation Runs (`/v1/automations/runs`)

Emails (`/v1/emails`)

Sends (`/v1/sends`)

Credits and Billing

Domains Lifecycle (`/v1/domains`)

Audiences (`/v1/audiences`)

Contacts + Fields (`/v1/contacts`, `/v1/fields`)

Analytics (`/v1/analytics/trigger-instances`)

Chat Context (`/v1/chats/{chatId}`)

SDK Error Handling (TypeScript)

Branching Agent / SDK Logic on `code`

See Also

Need Help?