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, usually because the complaint or bounce rate crossed a threshold. Reads still work. Open the dashboard: it shows the reason and a review button. Fix the list and request review.
`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.
`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.