Error codes

All error codes the Developer Email API can return, grouped by error.type. Codes marked with † carry extra fields in the error object — see the note under each. For the error object shape and handling patterns, see Errors.

---

invalid_request_error — 400, 409, 422

The request was well-formed but contained bad input. Fix the request body; retrying as-is returns the same error.

Code	HTTP	Meaning	Suggested action
missing_field	400	None of starter_template, template_id, or html was provided	Supply exactly one of the three
multiple_modes	400	More than one of starter_template, template_id, html was provided	Remove all but one
invalid_recipient †	400	One or more recipient addresses failed syntax or mail-server lookup	Check addresses; remove invalid ones
recipient_suppressed †	400	The recipient is on the platform-wide bounce/complaint suppression list	Address is globally blocked — contact support if you believe this is an error
recipient_limit_exceeded †	400	Combined to + cc + bcc exceeds 50 recipients	Split into multiple sends; use Spark for large-scale sends
batch_limit_exceeded †	400	Batch request exceeds 100 messages or 1,000 total recipients	Split into smaller batches
attachment_too_large †	400	A single attachment exceeds 5 MB, or all attachments combined exceed 7 MB	Reduce file size or link to the file instead of embedding
attachment_type_not_allowed †	400	Attachment content type is not in the allowlist	See Allowed attachment types below
too_many_attachments †	400	More than 10 attachments on a single message	Reduce to 10 or fewer; link to additional files instead
variable_validation_failed	400	Template variable values failed validation	Check variable names and value types against the template definition
idempotency_key_too_long	400	Idempotency-Key header exceeds 256 bytes	Shorten the key value
validation_failed †	422	Request body is structurally invalid — wrong field type, missing required field, unparseable JSON	Fix the field named in details.field
domain_already_exists	409	A domain with this hostname is already added for this account	No action needed — domain already exists
domain_in_use	409	Domain cannot be deleted because campaigns reference it	Reassign or delete the campaigns that use this domain first
domain_cannot_delete_default	400	Cannot delete the default sending domain	Set another domain as default in Settings → Email Setup, then delete

recipient_suppressed details:

"details": { "recipient": "user@example.com", "bounce_type": "hard" }

bounce_type is "hard" or "complaint".

recipient_limit_exceeded details:

"details": { "total": 55, "limit": 50 }

batch_limit_exceeded details:

"details": { "message_count": 120, "total_recipients": 800, "max_messages": 100, "max_recipients": 1000 }

attachment_too_large details:

"details": { "scope": "per_attachment", "size_bytes": 6291456, "limit_bytes": 5242880, "filename": "report.pdf" }

scope is "per_attachment" (5 MB cap) or "total" (7 MB cap).

attachment_type_not_allowed details:

"details": { "content_type": "application/x-executable", "filename": "setup.exe" }

too_many_attachments details:

"details": { "count": 13, "limit": 10 }

validation_failed details:

"details": {
  "field": "body.to",
  "errors": [{ "type": "missing", "loc": ["body", "to"], "msg": "field required" }]
}

---

authentication_error — 401

The request could not be authenticated. Check your API key.

Code	HTTP	Meaning	Suggested action
missing_api_key	401	X-API-Key header is absent	Add the X-API-Key header to every request
invalid_api_key	401	The API key is invalid, malformed, or has been revoked	Verify the key in Settings → API Keys; rotate if revoked
key_revoked_upgrade	401	The preview-tier key was revoked when the account was upgraded to a full account	Use the new bx_live_ key from Settings → API Keys

---

authorization_error — 403

The request was authenticated but is not permitted.

Code	HTTP	Meaning	Suggested action
upgrade_required †	403	The feature is only available on a paid plan	Upgrade at brixus365.com/pricing
tier_suspended	403	The account is suspended due to deliverability thresholds (bounce or complaint rate too high)	Check your rates in Connect → Dashboard; contact support to appeal
scope_required	403	The API key does not have the required scope for this endpoint	Issue a new key with the required scope in Settings → API Keys
no_verified_sender	403	No verified sending domain on this account	Verify a domain first — see Verify your sending domain
jwt_required	403	The endpoint requires dashboard login authentication, not an API key	This operation can only be performed from the dashboard — use the web UI instead

upgrade_required extras:

"upgrade_url": "https://brixus365.com/pricing"

---

not_found — 404

The requested resource does not exist or is not accessible from this API key.

Code	HTTP	Meaning	Suggested action
message_not_found	404	Message ID not found or belongs to a different API key	Check the message ID and that the key has emails:read scope
template_not_found	404	Template ID not found	Verify the template exists in Connect → Templates
domain_not_found	404	Domain ID not found	Check the domain ID in Settings → Email Setup

---

idempotency_error — 409

The Idempotency-Key header was used in a conflicting way.

Code	HTTP	Meaning	Suggested action
idempotency_key_mismatch	409	This key was previously used with a different request body	Use a new unique key, or re-send the original request body unchanged
idempotency_in_flight †	409	A concurrent request with this key is still processing	Wait and retry — the original request will complete shortly

idempotency_in_flight extras:

"retry_after_seconds": 5

---

rate_limit_error — 429

A send limit was reached. See Rate limits for thresholds and reset windows.

Code	HTTP	Meaning	Suggested action
rate_limit_exceeded †	429	Request rate too high — too many calls in a short window	Read the Retry-After header; wait, then retry
daily_limit_exceeded	429	Daily send quota reached	Wait for the daily reset, or upgrade your plan
monthly_limit_exceeded	429	Monthly send quota reached	Upgrade your plan to send more this month

rate_limit_exceeded extras:

"retry_after_seconds": 47,
"details": { "limit": 10, "window_seconds": 60 }

---

api_error — 500

An internal error that is not a client mistake.

Code	HTTP	Meaning	Suggested action
internal_error	500	Internal inconsistency on our side	Retry with exponential backoff; contact support if it persists

---

service_unavailable — 503

The email delivery provider is temporarily unavailable.

Code	HTTP	Meaning	Suggested action
provider_unavailable	503	Upstream provider temporarily down	Retry with exponential backoff

---

Sign-up API codes

These codes are only returned by the developer sign-up and account upgrade endpoints (/v1/auth/magic-link, /v1/auth/upgrade). You will not encounter them from the send or message endpoints.

Code	HTTP	type	Meaning
magic_link_invalid	401	authentication_error	The sign-in magic link is invalid or has expired — request a new one
already_signed_up	409	idempotency_error	This email address is already registered
not_a_preview_account	404	not_found	Email not registered as a developer preview account
already_upgraded	400	invalid_request_error	Account has already been upgraded — preview-to-full is a one-way transition

---

Allowed attachment types

The following MIME types are accepted. Any other content type returns attachment_type_not_allowed.

Category	MIME type	Common extension
Document	application/pdf	.pdf
Calendar	text/calendar	.ics
Image	image/png	.png
	image/jpeg	.jpg / .jpeg
	image/gif	.gif
	image/webp	.webp
Office	application/msword	.doc
	application/vnd.openxmlformats-officedocument.wordprocessingml.document	.docx
	application/vnd.ms-excel	.xls
	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	.xlsx
	application/vnd.ms-powerpoint	.ppt
	application/vnd.openxmlformats-officedocument.presentationml.presentation	.pptx
Text	text/csv	.csv
	text/plain	.txt

Attachment limits: 5 MB per file, 7 MB total across all attachments on a single message, 10 attachments maximum.

---

What’s next

You want to…	Go to
Understand the error object shape and handle errors in code	Errors
See request rate limits and monthly send quotas	Rate limits
Send your first email	Quickstart