# Usage limits

> Understand request limits, email and WhatsApp allowances, and how to recover when you reach them.

## Request sizes

| Operation | Limit |
| --- | --- |
| List domains or email logs | Up to 100 items per response; default 50 |
| Email recipients | 1–100 addresses per supplied recipient array |
| CC and BCC | Supported only with one primary recipient; `to`, `cc`, and `bcc` together at most 50 addresses |
| Page number on page-based lists | Up to 10,000 |
| Email analytics date range | Up to 366 days |
| Template versions | Up to 100 per response; default 50 |
| Email subject | Up to 500 characters |
| Sender display name | Up to 100 characters for transactional sends |
| WhatsApp recipients | One per request |
| WhatsApp variable values | Up to 1,024 characters each |
| `Idempotency-Key` for WhatsApp sends | Up to 200 characters |

## Sending and domain allowances

Sending allowances and the number of domains available depend on your subscription. They apply to the whole organization: domains in every project count toward the same domain allowance.

These responses need an allowance change, not a retry. Each has `error: "quota_exceeded"` (HTTP `429`) unless noted, and a `code`:

| Code | Returned when |
| --- | --- |
| `email_max_domains_exceeded` | Creating a domain would exceed the plan's domains. |
| `email_daily_limit_exceeded` | A send would exceed today's recipient allowance. To, CC, and BCC recipients all count; suppressed recipients do not. A scheduled send counts against the day it is scheduled for, including everything already scheduled for that day. |
| `email_max_scheduled_recipients_exceeded` | A scheduled send would exceed the recipients your plan allows to wait in scheduled emails at once. Recipients of a scheduled email you cancel keep counting for 24 hours. |
| `included_usage_exhausted` | The plan's included emails for the period are used up. |
| `wallet_balance_insufficient` | Paid usage is on, but the wallet cannot cover the send. |
| `paid_usage_disabled` | HTTP `403`: the included emails are used up and paid usage is off. |

Rapid retries do not increase your quota. A retried send with the same `Idempotency-Key` still returns its original response.

## WhatsApp allowances

Your plan includes a number of WhatsApp messages each billing period and a number of connected WhatsApp numbers for the whole organization. Beyond the included messages, each message is paid from your wallet and charged only once it is delivered. See [Costs](/docs/whatsapp/sending#costs).

| Code | Returned when |
| --- | --- |
| `included_usage_exhausted` | The plan's included WhatsApp messages are used up, and the plan has no paid messages. |
| `usage_spend_limit_exceeded` | The message would go past your spending limit. |
| `wallet_balance_insufficient` | The wallet cannot cover a message beyond the included ones. |
| `service_not_in_plan` | Your plan doesn't include WhatsApp messages. |
| `paid_usage_disabled` | HTTP `403`: the included messages are used up and paid usage is off. |

WhatsApp also limits how many different customers your business can message in 24 hours. That limit is set by Meta, not by your plan: messages past it become `failed`. See [Messaging limits](/docs/whatsapp/key-concepts#messaging-limits).

## Rate-limited requests

A rate-limited route returns HTTP `429`. Your organization's requests per second depend on your plan; past them, requests return `429` with `error: "quota_exceeded"` and code `api_rate_limit_per_second_exceeded` for a moment. Repeated requests with invalid API keys from one network are also refused with `429` and code `api_key_authentication_rate_limited` for about a minute; check the key you are sending. When `Retry-After` is present, wait at least that many seconds before retrying. Do not assume a universal requests-per-second allowance across endpoints.

Use bounded exponential backoff with jitter for transient failures. Avoid retrying validation or permission errors until you have corrected the request.

## Safe send retries

Reuse the same `Idempotency-Key` and payload when retrying the same send. Use a new key for a new message. The Node.js SDK accepts an explicit `idempotencyKey` option; store that value with your application operation so it survives a process restart.

See [Send an email](/docs/api/emails/send) and [Errors](/docs/api/errors).

---

Source: https://connect.nxiom.com/docs/api/usage-limits