Common issues

Most send failures fall into one of four categories: authentication, sender setup, recipient problems, or request validation. Find your error code below.

---

Authentication errors (401)

missing_api_key — no X-API-Key header

You sent the request without an X-API-Key header.

Fix: add the header to every request:

X-API-Key: bx_live_yourkey

---

invalid_api_key — wrong or revoked key

The key is malformed, belongs to a different account, or has been revoked.

Fix: open Settings → API Keys and copy the key again. If you recently rotated it, make sure you updated it in all integrations.

---

key_revoked_upgrade — preview key no longer valid

You upgraded your account but are still using the bx_test_* key from your preview session. Preview keys are revoked on upgrade.

Fix: go to Settings → API Keys, copy your new bx_live_* key, and replace the old one everywhere it is used.

---

Sender not set up (403)

no_verified_sender — no verified sending domain

Your account has no verified sender address. All outbound email requires a verified domain.

Fix: go to Settings → Email Setup, add your domain, and complete DNS verification. See Verify your sending domain for step-by-step instructions. Sends go through immediately once verification completes.

---

Recipient problems (400)

invalid_recipient — address failed validation

One or more addresses in to, cc, or bcc failed syntax validation or have no mail server (no MX record).

{
  "error": {
    "code": "invalid_recipient",
    "message": "One or more recipient addresses are invalid or have no mail servers.",
    "type": "invalid_request_error"
  }
}

Fix: check each address for typos. If the domain is correct but has no MX record, it does not accept email and you cannot send to it.

---

recipient_suppressed — address is globally blocked

The address previously produced a hard bounce or spam complaint on the platform. It is blocked platform-wide across all accounts.

{
  "error": {
    "code": "recipient_suppressed",
    "message": "Recipient is on the suppression list.",
    "type": "invalid_request_error",
    "details": {
      "recipient": "user@example.com",
      "bounce_type": "hard"
    }
  }
}

Fix: if you believe this is a mistake (e.g. the address was re-activated by its owner), contact support to request removal. Do not retry — the error will repeat until the address is removed from the list.

---

Request validation errors (422)

validation_failed — malformed request body

A required field is missing, a value has the wrong type, or the JSON is unparseable. details.field names the first failing path.

{
  "error": {
    "code": "validation_failed",
    "message": "field required",
    "type": "invalid_request_error",
    "details": {
      "field": "body.to",
      "errors": [
        { "type": "missing", "loc": ["body", "to"], "msg": "field required" }
      ]
    }
  }
}

Fix: check the field named in details.field. Common causes:

• body.to missing — the to field is required on every send
• body.to wrong type — must be a string or array of strings
• No content source — exactly one of html, template_id, or starter_template must be present

---

missing_field — no content source provided

None of html, template_id, or starter_template was provided.

Fix: add exactly one content field to your request body. See the send email reference for the full schema.

---

Rate limits and quotas (429)

If you are hitting 429 errors, see Rate limits for per-minute thresholds, daily and monthly quotas, and retry guidance.

---

Server errors (500 / 503)

internal_error (500) or provider_unavailable (503)

These are not caused by your request. A 500 is an internal inconsistency; a 503 means the delivery provider is temporarily unavailable.

Fix: retry with exponential backoff. If a 500 persists across retries, contact support with the timestamp and any message IDs returned in prior responses.

---

What’s next

You want to…	Go to
See every error code with description and suggested action	Error codes
Understand the error envelope shape	Errors
Understand rate limits and quotas	Rate limits