Reference

Errors

Every error has the same shape and a stable code. Match on the code, not the message.

The error envelope

HTTP/1.1 422 Unprocessable Entity
x-request-id: 5d1e9f0a-2b3c-4d5e-8f6a-7b8c9d0e1f2a

{
  "error": {
    "code": "validation_error",
    "message": "The request has invalid fields.",
    "docs": "https://www.sendbaze.com/docs/errors#validation_error",
    "fields": {
      "to": ["must be a valid email address"],
      "html": ["one of html, text or templateId is required"]
    }
  }
}

fields is present only on validation errors. Its keys are dotted paths into the request body, so a bad second recipient appears as to.1. Errors on the request as a whole use the key _.

Error codes

Code	Status	Meaning and what to do
`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 emails:send, sms:send or read scope, as the message states.
`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. The complaint-rate monitor pauses an organisation at 3 or more complaints and a complaint rate of 0.1% or more over 24 hours. Reads and test keys still work. The dashboard Overview shows the reason. Clean your lists (the Suppressions page lists who complained), make sure marketing email is opt-in only, then email support@sendbaze.com for a review.
`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 from your list. If it was added by mistake, remove it on the Suppressions page or with DELETE /v1/suppressions/{id}; hard bounces are global and cannot be removed.
`not_found`	404	No message with that id belongs to your organisation. Check the id and that you are using the key of the organisation that sent 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. The fields object lists every problem by path. Fix each listed field. Unknown fields are rejected too, so check for typos.
`insufficient_credits`	402	The organisation does not have enough SMS credits for this message. Top up in the dashboard. Email does not use credits.
`idempotency_conflict`	409	This Idempotency-Key was already 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.
`rate_limited`	429	More than 100 requests per second from this organisation. Wait for the number of seconds in the Retry-After header, then retry. Use the batch endpoints for bulk sends.
`domain_not_verified`	403	The from address is not on a verified sending domain of this organisation. Live keys can only send from domains you have proved you own. POST /v1/domains with the domain, publish the DNS records it returns, then wait for status "verified" (usually minutes; POST /v1/domains/{id}/verify checks now). Subdomains of a verified domain are covered.
`already_exists`	409	The resource already exists and belongs to another organisation, for example a domain someone else registered. If you own the domain, contact support with proof of DNS control and we will move it.
`plan_allowance_exceeded`	402	Your plan's monthly email or SMS allowance for the current billing period is used up. Nothing was queued. GET /v1/usage shows the reset time. Upgrade in the dashboard to keep sending now; SMS also continues on prepaid credits.
`plan_limit_reached`	402	Your plan's limit on a resource (for example verified domains) is reached. Remove one, or upgrade in the dashboard.
`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, not a problem with your domain. Retry in a few minutes. If it keeps failing, email support@sendbaze.com with the domain name.
`internal_error`	500	Something failed on our side. Nothing was sent. Retry with the same Idempotency-Key. If it persists, send us the x-request-id.

Errors inside a batch

Batch endpoints return 200 even when some items fail. Each result has ok and either data or an error in the same envelope shape as above, so one bad recipient never rejects the other 999.