LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Limits and pacing

Use with AI

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#

LimitValueWhat happens when you go past it
Requests per key600 per minute429 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 secondsNothing 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 number55 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 number5,000 pending messages429 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 /typingThey share the number’s per-second pace429 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 limiteDiarioDeConversasMeta 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 number429 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 message4096 characters400 with campos. See Send messages.
typingMs1 to 25000 milliseconds400 with campos. See Send messages.
File uploaded to Luna100 MB413 with error: "file_too_large", before any call to Meta.
Webhook endpoints per account25409 with error: "webhook_endpoint_limit". Removing one frees the slot.
Time your endpoint has to answer10 secondsThe 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 the Retry-After and repeat with the same Idempotency-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 sleep between 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, and sent arrives 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_changed event announces it. See Account health.
  • Went past the ceiling: Meta refuses the send and the reason arrives in message.status (failed), in the error field. 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.