Limits and pacing
The rule for every Luna limit fits in one sentence: it exists for infrastructure capacity and is the same for every customer. None varies with price. This page gathers the ones that matter to whoever sends a lot, an AI agent for example, with what each one does when you go past it.
The live list, with each limit’s value and reason, is at GET /v1/limits (numbers:read scope). Each route’s contract is in the API reference.
The limits, in one table#
| Limit | Value | What happens when you go past it |
|---|---|---|
| Requests per key | 600 per minute | 429 with error: "rate_limited" and Retry-After. Wait the indicated time. See Errors. |
| Burst of each conversation (the same origin number and the same recipient) | 30 messages at once, then one every 7 seconds | Nothing fails: the message waits in the queue and goes out in order. The 202 comes back the same, and this limit never becomes a 429. |
| Sends per number | 55 per second (20 per second on a number in coexistence) | What goes past the pace waits in the queue and goes out in order. The live value is at GET /v1/limits. |
| Send queue per number | 5,000 pending messages | 429 with error: "queue_full" and Retry-After, the time the queue takes to drain. Nothing was accepted: repeat later, with the same Idempotency-Key. |
/read and /typing | They share the number’s per-second pace | 429 with error: "number_rate_limited" and Retry-After. They are synchronous and lose their value with time: if you go past it, wait and try, or leave it to the reply. |
| New conversations per day (Meta’s) | The tier in limiteDiarioDeConversas | Meta refuses the send and the reason arrives in message.status with failed. See the section below. |
| Business account management operations (creating and editing templates, for example) | 150 per hour on an account with no registered number, and 3,750 per hour with a number | 429 with error: "management_busy" and Retry-After. The ceiling is shared with the number connection, so a loop that creates many templates can delay a connection. |
| Text of a message | 4096 characters | 400 with campos. See Send messages. |
typingMs | 1 to 25000 milliseconds | 400 with campos. See Send messages. |
| File uploaded to Luna | 100 MB | 413 with error: "file_too_large", before any call to Meta. |
| Webhook endpoints per account | 25 | 409 with error: "webhook_endpoint_limit". Removing one frees the slot. |
| Time your endpoint has to answer | 10 seconds | The delivery counts as a failure and is retried. See Receive events. |
What waits and what fails#
There are two families of limit, and the difference decides your code. The pace ones (the burst of each conversation and sends per number) never fail: the message is accepted with 202 and Luna delivers it when the pace allows, in order. The refusal ones (requests per key, full queue, /read and /typing) answer 429 with Retry-After, and nothing was accepted.
- On a
429, wait theRetry-Afterand repeat with the sameIdempotency-Key: if the first attempt got through, the repeat returns the original message instead of sending twice. - An agent that replies in bursts needs no
sleepbetween messages: the wait happens in Luna’s queue. - The burst holds within each conversation: a slow conversation does not delay the other ones of the same number.
- The state of a message that waits is
queued, andsentarrives when it goes out. See Send messages. - The ready-made retry code, in Node and Python, is in Errors.
The daily conversation limit#
This is a limit from Meta, and Luna only shows it. GET /v1/numbers returns, on each number, limiteDiarioDeConversas: the name of the tier Meta placed the business portfolio in (TIER_250, TIER_2K, TIER_10K, TIER_100K or TIER_UNLIMITED; Meta may add others). It counts unique people the business starts a conversation with outside the service window, in a 24-hour period, and not messages, and it is the same for all numbers in the portfolio. Talking to someone who wrote first, inside the 24-hour window, does not count.
- The field says the ceiling Meta granted, and never how much you have used. There is no route that returns consumption.
- The initial limit. A new business portfolio starts at
TIER_250: 250 unique people you start a conversation with per 24-hour period (Meta documentation). People who wrote first inside the service window do not count. To go up, Meta asks for the business to be verified (or the partner that connected it), or for 2,000 delivered messages outside the window, to unique people and with good-quality templates, within 30 days; after that the rise is automatic (10 thousand, 100 thousand, unlimited) with high quality and use of half the current limit in 7 days. For a new customer, plan the first mass send below 250 people a day. - When Meta changes the tier, the
account.limit_changedevent announces it. See Account health. - Went past the ceiling: Meta refuses the send and the reason arrives in
message.status(failed), in theerrorfield. See Errors. - Do not confuse it with
throughputLevel, which is speed (messages per second) and not the number of conversations.
What no limit is#
No limit on this page is a quota per plan. Luna’s plan defines one thing only: how many numbers the account keeps active (Plan and numbers). The request ceiling, the pace and the queue are the same for everyone, and exist for capacity.