> ## 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

> The error envelope and how to handle each class of error in code.

Every error response has the same shape:

```json theme={"dark"}
{
  "error": {
    "code": "recipient_suppressed",
    "message": "1 recipient is on a suppression list.",
    "docs": "https://docs.sendbaze.com/errors#recipient_suppressed",
    "fields": { "to": ["gone@example.co.za: hard_bounce (global)"] }
  }
}
```

## Handling by class

| Status | What to do in code |
| - | - |
| `400`, `422` | A bug or bad input on your side. Log `fields`, do not retry unchanged. |
| `401`, `403` | Configuration: wrong key, missing scope, unverified domain. Alert, do not retry. |
| `402`, `423` | Account state: allowance, credits, pause. Alert an operator; retry after the condition clears. |
| `404` | The id is wrong or belongs to another organisation. |
| `409` | Idempotency conflict: your retry changed the body. Fix the key strategy. |
| `413` | Attachments too large: shrink or link. |
| `429` | Wait `Retry-After` seconds, then retry with the same `Idempotency-Key`. |
| `500`, `503` | Retry with backoff and the same `Idempotency-Key`. |

The [full list of codes](https://docs.sendbaze.com/errors.md) explains each one.

## Validation fields

`fields` maps a dotted path to one or more messages. Arrays use the index (`to.1`), template variables use the name (`variables.eta`), and problems with the request as a whole use `_`.

```json theme={"dark"}
{
  "fields": {
    "to.1": ["must be a valid email address"],
    "html": ["one of html, text or templateId is required"],
    "extra": ["is not a recognised field"]
  }
}
```

Unknown fields are rejected. This catches typos such as `reply_to` for `replyTo` before they silently do nothing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.