Skip to content

API and SDK

Limits

The limits of the Messajo API, of sending per number, of Meta and of data retention.

Each key and each organization has a per-minute request limit. Both apply at once: a call goes through only if it fits in both.

Scope Default limit
Per API key 600 requests/min (adjustable per key up to 6,000/min)
Per organization (all keys combined) sum of active connections’ throughput x 60 x 1.25, at least 1,200 requests/min

Both limits apply to both key types (organization mj_ and connection mjc_). The per-key limit belongs to each key: every connection key has its own counter of 600 requests/min. The organization limit is a single one and adds up the traffic of all keys, connection keys included, so several connection keys together still share the same organization throughput.

Every /v1 API response carries the headers of the current window:

Header What it is
X-RateLimit-Limit Window limit
X-RateLimit-Remaining How many calls still fit in the window
X-RateLimit-Reset When the window resets (Unix, in seconds)

Over the limit, the response is 429 with the rate_limited code, the Retry-After header (seconds) and the retry_after_ms field in the body. Wait that long before retrying.

The organization limit follows its connections: two numbers at 80 and 20 messages/s give 7,500 requests/min (100 x 60 x 1.25). Instagram and Messenger only count if they have a recorded throughput. The value is recalculated every 60 s, so connecting or removing a number takes up to 1 minute to apply; X-RateLimit-Limit shows the limit in effect. The other values may change per plan.

Each number has a maximum throughput, which depends on the connection mode. Messajo reads the throughput together with the number’s health, every 15 minutes, and shows it as Speed on the connection page:

Mode Throughput
Coexistence (phone app + API) 20 messages/s
API only 80 messages/s
API only, with high throughput granted by Meta 1,000 messages/s (Meta raises it automatically)

Each number has a token bucket with the throughput as its capacity (20, 80 or 1,000), refilled at that rate per second. Every call that goes to Meta spends one token: the send, through the simple layer or the mirror, and typing. With no token left, Messajo answers 429 with the connection_rate_limited code, the Retry-After header and retry_after_ms in the body, without calling Meta. Nothing is queued: wait that long and retry with the same Idempotency-Key.

If Meta itself rejects for throughput (130429, 80007 or 4 in meta_code), the response is 429 meta_rate_limited. Since Meta did not process the request, Messajo retries on its own when the wait fits in 2.5 s; beyond that, it returns the error with the retry_after_ms Meta gives.

Meta limits how many unique users the portfolio (Business Manager) reaches with business-initiated messages in a rolling 24 hours. The limit belongs to the portfolio and is shared by all its numbers.

The tiers are 250 → 2,000 → 10,000 → 100,000 → unlimited. To move up:

  • verify the business in the portfolio, or
  • keep good quality and message at least half of the current limit within 7 days.

Meta re-evaluates the portfolio every 6 hours and raises the tier on its own when the conditions are met. Messajo reads the current tier (the number’s whatsapp_business_manager_messaging_limit field) together with health and shows it as Messaging tier on the connection page; when it changes, connection.updated goes out with reason: "limit_changed". Replies inside a conversation opened by the contact do not count toward this limit. Campaigns stop on their own at 95% of the tier and resume when it frees up.

Official details: Meta messaging limits.

Meta also limits how many messages a number sends to the same contact in a short time (roughly one message every 6 seconds, with small bursts). Above that, the response is 429 pair_rate_limited, with 131056 in meta_code and a retry_after_ms of 6,000: wait and space out the sends to that contact. Messajo never retries this error on its own.

Channel Rule
WhatsApp Up to 24 hours after the contact’s last message, any message. Outside it, only an approved template.
Instagram and Messenger Up to 24 hours after the contact’s last message; 7 days after the contact replies to an ad. With tag: "human_agent" (replies from a person only), up to 7 days. Outside it, 422 before calling Meta.

On WhatsApp, Messajo checks the window before calling Meta: a non-template message outside the window comes back 422 outside_service_window, with the end of the window in details[0].message. Only the contact’s message opens the window; what you send from the phone app in coexistence does not.

Each Instagram account and each Messenger Page has a token bucket, like WhatsApp numbers. Without a token, the answer is 429 connection_rate_limited, without calling Meta.

Channel Text, reaction, like, buttons and cards Media (image, images, audio, video, PDF)
Instagram 100 messages/s 10 messages/s (also spends a text token)
Messenger 100 messages/s 100 messages/s
Limit Instagram Messenger
Text 1,000 bytes 2,000 characters
Images per message up to 10 (images) 1
Attachment image up to 8 MB; audio, video and PDF up to 25 MB 25 MB
Publications 100 per account in 24 h (publications) —

If Meta itself rejects for throughput (4, 17, 32, 613 or 80006), the answer is 429 meta_rate_limited with the retry_after_ms Meta reports. There is no bulk sending and no campaigns on Instagram and Messenger: Meta does not allow it. The numbers above come from the Instagram Platform and Messenger Platform docs and are still being checked on a real account.

Limit Value
Call permission request (Meta) 1 per 24 h and 2 per 7 days for the same contact (Calls)
Call SDP 64 KiB
Participants per group 8 (Groups)
Flow JSON 10 MiB; PUT /v1/flows/{id}/json up to 30 per minute per organization
Exchanges on a Flow endpoint 1,200 per minute per Flow; your handler has 7 s and up to 256 KiB of response (Flows)
Items per order 100 (Selling)
Media upload (POST /v1/media) 120 per minute per organization
Route Maximum
/v1 (JSON) 1 MiB
POST /v1/media 100 MiB
POST /v1/campaigns/{id}/recipients 20 MiB
PUT /v1/flows/{id}/json 10 MiB
Panel (/rpc) 2 MiB

Above that, the response is 413 body_too_large, with nothing processed.

Data Period
Raw event received from Meta 7 days
Events and delivery records 30 days (or the organization’s deadline, if shorter)
Panel logs (API requests) 30 days (or the organization’s deadline, if shorter)
Messages, media, conversations and contacts 90 days by default; the owner chooses from 7 up to the instance ceiling

After the period, the data is deleted in the daily purge. Details in Data and privacy.

Send the Idempotency-Key header (a unique value per operation, such as a UUID) on calls that create something, like sending a message. The key is valid for 24 hours: repeating the same key within that period returns the original response without running it again. That is how you safely retry a send after a timeout.