> ## Documentation Index > Fetch the complete documentation index at: https://docs.sendbaze.com/llms.txt > Use this file to discover all available pages before exploring further. # Errors > Every error shares one envelope with a stable code. This page lists each code, its HTTP status, what it means and what to do. ## The envelope ```json theme={"dark"} { "error": { "code": "validation_error", "message": "The request has invalid fields.", "docs": "https://docs.sendbaze.com/errors#validation_error", "fields": { "to.1": ["must be a valid email address"] } } } ``` * `code` is stable; branch on it, not on `message`. * `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` and a missing template variable as `variables.eta`. Errors on the request as a whole use the key `_`. * Every response also carries an `x-request-id` header. 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](mailto: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](https://docs.sendbaze.com/get-started/test-without-a-domain.md). ### 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.`. ### 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](https://docs.sendbaze.com/learn/deliverability/reputation.md#warm-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 return `200` 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.