The envelope
codeis stable; branch on it, not onmessage.fieldsis present only on validation errors. Its keys are dotted paths into the request body, so a bad second recipient appears asto.1and a missing template variable asvariables.eta. Errors on the request as a whole use the key_.- Every response also carries an
x-request-idheader. Quote it when you write to support.
Codes
unauthorized
401 The Authorization header is missing, malformed, or the key is revoked. Send Authorization: Bearer sk_live_… or sk_test_…; create a new key if this one was revoked.
insufficient_scope
403 The key is valid but lacks the scope this endpoint needs. Create a key with the scope the message names (emails:send, sms:send, domains:write, webhooks:write or read).
org_suspended
403 The organisation has been suspended for an Acceptable Use Policy breach or non-payment. Contact support@sendbaze.com.
org_paused
423 Sending is paused by the complaint monitor (3 or more complaints and a rate of 0.1% or more over 24 hours) or by an operator. Reads and test keys still work. The dashboard Overview shows the reason; clean your lists, make sure marketing email is opt-in only, then email support for a review.
domain_not_verified
403 The from address is not on a verified sending domain of this organisation. POST /v1/domains with the domain, publish the DNS records it returns and wait for status verified. Subdomains of a verified domain are covered. Before your domain is verified you can send to your own addresses from onboarding@sendbaze.com; see send before your domain is verified.
sandbox_recipient_not_allowed
403 The from address is the shared test address onboarding@sendbaze.com, which only delivers to your organisation’s own addresses (the sign-in email of every member and the billing email, +labels included) and to the Amazon SES simulator addresses. A to, cc or bcc address is none of those; fields.to names each one. Nothing was queued. To email anyone else, add and verify your own domain at the domainsUrl in the error body.
sandbox_limit_reached
403 Your organisation has sent its 100 emails from the shared test address onboarding@sendbaze.com; the total is for the organisation’s whole life. Nothing was queued. The body carries limit and a domainsUrl: add and verify your own domain to keep sending, from your own address and to anyone.
not_found
404 No resource with that id belongs to your organisation. Check the id and that you are using a key of the organisation that owns it.
invalid_json
400 The body is empty or is not valid JSON. Send a JSON body with Content-Type: application/json.
validation_error
422 One or more fields are invalid; fields lists every problem by path. Unknown fields are rejected too, so check for typos. A template placeholder you did not supply appears as variables.<name>.
recipient_suppressed
422 A to, cc or bcc address is on a suppression list: it bounced permanently, complained, unsubscribed (marketing only) or was added by your team. Nothing was queued; fields.to names each address and its reason. Drop the address, or remove the entry on the Suppressions page if it was added by mistake.
payload_too_large
413 The attachments on this email exceed the limit: 3 MB decoded in total and 10 files. Nothing was queued. Send smaller files or link to a download.
insufficient_credits
402 Nothing is included for this send (pay as you go, or SMS on Free) and the wallet does not cover it. Nothing was queued. Top up the wallet at the topUpUrl in the error body; GET /v1/usage shows the balance.
allowance_exhausted
402 Your plan’s included emails or SMS for the billing period are used up and nothing else covers the send: the wallet is empty and there is no saved card for overage. Nothing was queued. GET /v1/usage shows the reset time. To keep sending now, top up the wallet (topUpUrl), save a card for overage, or upgrade (upgradeUrl). On Free, upgrade or switch to pay as you go. Replaces plan_allowance_exceeded.
spend_cap_reached
402 Postpaid overage for this billing period has reached your spend cap, so the send was not accepted. Raise the cap on the Billing page, or top up the wallet: wallet funds are used before overage.
payment_required
402 Usage beyond your allowance has been unpaid for more than 24 hours after your saved card was declined, so live sending is paused. Test keys still work and nothing is deleted. Pay the amount due on the Billing page (upgradeUrl in the error body) and sending resumes at once. Before this point you are emailed when the charge fails and again when the automatic retry 12 hours later fails. An unpaid plan renewal does not cause this error: after the same 24 hours the plan is paused and the organisation moves to the Free plan, with an email saying how to restore it from the Billing page.
daily_cap_reached
429 The Free plan’s daily limit on live emails is used. Nothing was queued. Wait for Retry-After (the next UTC day), or upgrade at upgradeUrl to remove the daily cap.
plan_limit
403 Your plan’s limit on a resource is reached (sending domains, webhook endpoints, team seats), or the resource is beyond the limit after a downgrade and is read-only. The body carries limit and an upgradeUrl. Remove one, or upgrade. Nothing is deleted on a downgrade; extra domains simply cannot send until you are back within the limit. Replaces plan_limit_reached.
idempotency_conflict
409 This Idempotency-Key was used in the last 24 hours with a different body or on a different channel. Use a new key for a new message; reuse a key only to retry the exact same request.
already_exists
409 The resource already exists: a template with that name in your organisation, or a domain registered by another organisation. If you own the domain, contact support with proof of DNS control.
rate_limited
429 More than 100 requests per second from this organisation. Wait for the seconds in the Retry-After header, then retry. Use the batch endpoints for bulk sends.
warmup_limit_reached
429 Your organisation is warming up and today’s cap on live email is used. Nothing was queued. Retry-After counts down to the next UTC day, when the cap doubles if your bounce rate stayed under 2%. GET /v1/usage shows the cap and what was sent.
destination_not_supported
422 The number is in a country Sendbaze does not send SMS to, or one whose route is not live yet. Nothing was queued. SMS covers South Africa and other African countries; GET /v1/sms/coverage lists them with available per country. In a batch, only the items to that country fail.
destination_not_enabled
403 The country is live but your organisation has not enabled it. Nothing was queued, nothing was charged. An owner or admin adds the country on the Settings page (settingsUrl in the body). Every organisation starts with South Africa; the list is a guard rail against a leaked key sending abroad.
sms_velocity_exceeded
429 A live SMS would break a velocity rule: more than your organisation’s segments per minute (300, or 60 on Free and pay as you go), more than 8 messages an hour or 20 a day to one number, or a burst of new numbers on one prefix from a young organisation. Nothing was queued. Wait for Retry-After, then retry; email support if the traffic is expected and you need a higher budget.
email_provider_unavailable
503 Sendbaze could not reach Amazon SES to create, check or delete a domain. Nothing was changed; this is on our side. Retry in a few minutes.
service_unavailable
503 A part of Sendbaze this request needs is not available right now; the message says which. Nothing was changed. Retry later, and email support with the x-request-id if it persists.
internal_error
500 Something unexpected failed on our side. It is logged with the request id; retry, and tell support the x-request-id if it repeats.
Errors inside a batch
Batch endpoints return200 even when some items fail. Each result has ok and either data or an error in the envelope shape above, so one bad recipient never rejects the other 999.