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

# Errors

> Error codes and handling for the Sendmux Sending API.

The Sending API uses the same error envelope as the [Management API](/docs/api/errors): `code`, `message`, `param`, `doc_url`, `retryable`, accumulated `errors[]`, `X-Request-Id`, and `Retry-After` on `429` or `503`. This page documents only the codes the Sending API emits.

## Error response format

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "insufficient_credits",
    "message": "A human-readable description of the error.",
    "param": "to.email",
    "doc_url": "https://sendmux.ai/docs/sending-api/errors#insufficient_credits",
    "retryable": false
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

`param` is only present when the error is tied to a specific request field. On accumulated validation failures, `error.errors` carries every issue. See [Validation errors with multiple issues](/docs/api/errors#validation-errors-with-multiple-issues). Always include `request_id` or the `X-Request-Id` response header when contacting support.

## Shared error codes

These codes are shared with the Management API. Their semantics are identical to the matching sections in the [Management error reference](/docs/api/errors).

### authentication\_required

**HTTP 401**: The request has no `Authorization` header or the API key is invalid, expired, or revoked.

### insufficient\_permissions

**HTTP 403**: The API key is valid but lacks the `email.send` permission, the sender is not authorised for that key, or the mailbox is not active.

### invalid\_parameter

**HTTP 400**: A request field has an invalid format or value, or the JSON body failed schema parsing. The `param` field identifies the offending field. `errors[]` lists every issue when more than one is present.

### missing\_parameter

**HTTP 400**: A required request field is missing from the body.

### not\_found

**HTTP 404**: A referenced resource, such as a `from` mailbox or domain, does not exist or belongs to a different team than the one associated with your API key.

### rate\_limit\_exceeded

**HTTP 429**: You have exceeded the rate limit of 1800 requests per minute. The response carries a `Retry-After` HTTP header with the recommended wait in seconds. Back off until then before retrying. `retryable` is `true`.

### internal\_error

**HTTP 500**: An unexpected server error occurred. `retryable` is `true`. If this persists, contact support with the `request_id`.

## Sending-specific error codes

### insufficient\_credits

**HTTP 402**: Your team's balance is too low to send this email or batch. Top up your balance under **Billing**.

### validation\_error

**HTTP 422**: The request body failed schema validation. Check the `param` field for the specific field that caused the error.

Common causes:

* Missing required fields (`from`, `to`, `subject`, `html_body`)
* Invalid email addresses
* Attachment file type not in the allowed list
* Uploaded attachment refs that expired or belong to a different team
* Batch exceeds 100 messages

### idempotency\_conflict

**HTTP 409**: Returned when the same `Idempotency-Key` request header is reused while the original request is still running, or with a request body that does not match the original body fingerprint. Wait and retry for an in-flight request. Use a fresh key for a different request.

### payload\_too\_large

**HTTP 413**: The request body, binary attachment upload, or final encoded message exceeds the maximum allowed size. `html_body` and `text_body` are capped at 25MB each. Inline base64 attachments count towards the JSON request body. Uploaded attachment bytes are capped separately, and the final sent message must still fit within 25MB.

### no\_active\_providers

**HTTP 503**: Your team has no active sending account. Every team starts with the managed Amazon SES account active, so this usually means it was deactivated and no other provider is active. Reactivate the managed account, or add and activate a provider under **Accounts**. See [Sending accounts](/docs/guides/sending-accounts). `retryable` is `true`, but retrying will keep failing until an account is active.

### service\_unavailable

**HTTP 503**: A required service is temporarily unavailable. The response may carry a `Retry-After` header. `retryable` is `true`, so back off and retry. If this persists for more than a few minutes, contact support with the `request_id`.