> ## 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 Qubrics Sending API.

The Sending API uses the same error envelope as the [Management API](https://sendmux.ai/docs/api/errors.md): `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://qubrics.com/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](https://sendmux.ai/docs/api/errors.md#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](https://sendmux.ai/docs/api/errors.md).

### 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**: The balance of your team is too low for sending this email or batch. Top up the team balance under **Billing**.

### billing\_restricted

**HTTP 403**: Sending is blocked by the team's billing status. Review **Billing** before retrying. A Free team with depleted credit must upgrade to Pro. Contact support if a paid team is unexpectedly read-only.

### daily\_limit\_exceeded

**HTTP 429**: A Free team's accepted and in-flight recipients have reached the limit of 50 for the current UTC day. The message is rejected before it enters the delivery queue. Wait for the `Retry-After` period or upgrade the team to Pro before retrying.

In a batch response, individual messages can fail with `daily_limit_exceeded` while earlier messages are queued. If every message hits the daily cap, the whole request returns this code.

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

### invalid\_delivery\_group

**HTTP 422**: The per-message `delivery_group` hint is malformed or ambiguous. Supply one group public ID or a nonempty array, with at most 50 groups and no empty entries. Use the dedicated field instead of `X-Qubrics-Delivery-Group` in `custom_headers`. `retryable` is `false`.

### delivery\_group\_not\_found

**HTTP 422**: A requested delivery group does not exist or belongs to another team. `retryable` is `false`.

### delivery\_group\_not\_allowed

**HTTP 403**: A requested group is outside the credential's configured delivery groups. Narrow the hint to an authorised subset. `retryable` is `false`.

### delivery\_group\_scope\_invalid

**HTTP 422**: The credential is scoped to specific providers and cannot use a delivery-group hint. Omit the hint or use a credential with an appropriate group or all-provider scope. `retryable` is `false`.

These routing errors remain indexed in batch results, including when every message fails routing. Shared-domain sending ignores the hint before routing validation. See [Delivery groups](https://sendmux.ai/docs/sending/accounts/delivery-groups.md#restrict-one-message).

### 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](https://sendmux.ai/docs/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`.


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