> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pulse-send.jiordiviera.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> One error format, a stable code for each case.

Failed requests return a `4xx` or `5xx` status and a JSON body:

```json theme={"dark"}
{
    "error": {
        "type": "validation_error",
        "code": "domain_not_verified",
        "message": "The sender's domain is not verified.",
        "param": "from",
        "doc_url": "https://docs.pulse-send.jiordiviera.me/errors#domain_not_verified"
    }
}
```

| Field | Description |
| - | - |
| `type` | The category. It decides the HTTP status. |
| `code` | A stable, specific code. Branch your logic on this one. |
| `message` | A readable explanation. It may change; don't parse it. |
| `param` | The request field at fault, when there is one. |
| `doc_url` | A link to the code below. |

Every response also carries an `X-Request-Id` header. Include it when you contact support.

## Types

| Type | Status | Retry? |
| - | - | - |
| `authentication_error` | 401 | No. Fix the key. |
| `insufficient_credits` | 402 | After a top-up. |
| `permission_error` | 403 | No. |
| `not_found` | 404 | No. |
| `idempotency_error` | 409 | Depends on the code. |
| `validation_error` | 422 | No. Fix the request. |
| `rate_limit_error` | 429 | Yes, after `Retry-After`. |
| `api_error` | 500 | Yes, with backoff and an idempotency key. |

## Codes

### missing\_api\_key

No `Authorization: Bearer ps_…` header. See [Authentication](/authentication).

### invalid\_api\_key

The key doesn't exist or was revoked. Create a new one in the dashboard.

### insufficient\_credits

The live send needs more credits than your team has. Nothing was sent. [Top up](/guides/credits) and retry.

### missing\_scope

The key doesn't have the scope this endpoint needs, for example `emails:send`. See [Scopes](/authentication#scopes).

### team\_paused

Sending is paused for your team, usually after high bounce or complaint rates (see [Sending reputation](/guides/limits#sending-reputation)). Contact support.

### resource\_missing

The ID doesn't match anything your team owns.

### idempotency\_key\_reused

You reused an `Idempotency-Key` with a different body. Use a new key for a new request. See [Idempotency](/guides/idempotency).

### idempotency\_in\_progress

A request with the same `Idempotency-Key` is still running. Wait a moment and retry.

### idempotency\_key\_too\_long

`Idempotency-Key` is limited to 255 characters.

### invalid\_parameter

A field is missing or malformed. `param` names it and `message` says what's wrong.

### missing\_body

The email has neither `html` nor `text`. Send at least one.

### too\_many\_recipients

More than 50 recipients across `to`, `cc` and `bcc`. Split the send.

### domain\_not\_verified

With a live key, the `from` address must belong to a [verified domain](/guides/domains).

### all\_recipients\_suppressed

Every recipient is on your suppression list after a hard bounce or a complaint. Nothing was sent.

### rate\_limited

More than 10 requests per second on this key. Wait `Retry-After` seconds.

### internal\_error

Something broke on our side. Retry with backoff, using an idempotency key. If it persists, contact support with the `X-Request-Id`.


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