Skip to content

Glossary drawing · Graph API & SDKs

Pair Rate Limit

Also called: Error 131056 · Per-recipient rate limit · Business-consumer pair rate limit

Note 1 —A WhatsApp Cloud API limit on how fast one business number can message the same user. Sustained rapid sends to one recipient fail with error 131056.

Term
Pair Rate Limit
Abbreviation
—
Category
Graph API & SDKs
Level
Practitioner
Reviewed
Sheet no.
GLO-API-436
Drawn by
InfiQ Glossary

Drawing 1 · Interactive

Back off one recipient, not the whole number

3 / 3

Attempt 3 of 5

t = 5 s

SucceededDelivered after 2 retries
  1. Attempt 1 at 0 ms: failed.
  2. Attempt 2 at 1 s, after waiting 1 s: failed.
  3. Attempt 3 at 5 s, after waiting 4 s: succeeded.

The delay formula · retry n = 1

delayn = base × factorn

= 1 s × 41 = 4 s

sleep = delay = 4 s

Fires at t = 5 s, 4 s after attempt 2.

24 clients, same outage · retry n = 1

Without jitter all 24 retry at exactly 4 s: a thundering herd that can knock the server over again.

A send to one user returns 131056. Retries to that recipient follow Meta's suggested 4^X-second schedule (1 s, 4 s, 16 s…) until one succeeds. Switch on jitter to see how random waits spread retries out. Other recipients never wait.

Attempt 3 at 5 s succeeded.

What is the pair rate limit?

The pair rate limit is a WhatsApp Cloud API limit on messages between one pair: a single business phone number and a single WhatsApp user. If a number sends too many messages to the same recipient in a short period, further sends to that user are refused with error code 131056. In Meta's error reference, the cause is a sender number messaging the same recipient number too often in a short time.

It is separate from throughput. Throughput caps the total messages per second a number can send across all recipients: 80 per second by default, with an automatic upgrade path to 1,000. Exceeding throughput returns error 130429. The pair limit applies even when you are far below throughput. A number sending ten messages a second spread across thousands of users is fine, while a number firing a rapid series at one user can be throttled for that user alone.

The limit tolerates short bursts: a reply followed by a couple of follow-up bubbles is normal conversation. What it throttles is sustained rapid sending to one person: a burst borrows from the pair's future allowance, so the sender then has to wait before that user can receive more. Meta's guidance is to retry after 4^X seconds (1, 4, 16 and so on, with X rising after each failure), and its error reference notes that you can keep messaging other numbers without waiting. So the right design is a per-recipient queue with backoff, not a global slowdown, and not a hard-coded per-user rate that breaks when Meta tunes the limit.

Key takeaways

  • The pair rate limit caps how quickly one business number can send to one WhatsApp user, separately from overall throughput.
  • Hitting it returns error 131056. Other recipients are unaffected, so only that user's queue should pause.
  • Short bursts are tolerated, but sustained rapid sends to a single recipient are throttled.
  • Don't hard-code a per-user rate. Pace each recipient and back off on 131056, retrying after 1, 4, 16… seconds as Meta suggests.
  • The usual causes are bots that split one answer into many bubbles, and retry loops that resend the same message.

Design intent

Why does the pair rate limit matter?

Error 131056 tends to appear exactly where it hurts. A chatbot answers one question with six separate messages. An order flow sends the confirmation, invoice, tracking link and survey in the same second. A retry loop resends on every timeout. Each failure is a message the customer never sees. The naive fix, pausing the whole sender, delays every other conversation too. Handling the limit per recipient stops one noisy thread from slowing the entire number.

Operating sequence

How does the pair rate limit work?

  1. Messages leave one number for one user

    Every send counts against the pair: your phone number ID and the recipient's WhatsApp ID. Sends to other users count only against throughput.

  2. Short bursts pass

    A handful of messages in quick succession is normal conversation and is usually accepted.

  3. Sustained rapid sends trip the limit

    Keep sending to the same user at a high rate, and the API starts refusing sends to that recipient with error 131056. The code can come back in the API response or in a failed status webhook.

  4. Back off for that recipient only

    Hold that user's queue and retry with exponential backoff and jitter. Keep sending to everyone else at full speed, because other recipients are not affected.

  5. Send fewer messages

    For the long term, merge bubbles into one message, use interactive lists or buttons instead of a series of texts, and space out automated sequences.

Implementation

The pair rate limit in code

// One queue per recipient: a 131056 pauses only that user's sends.
const queues = new Map(); // wa_id -> promise chain
const URL = "https://graph.facebook.com/v26.0/" + process.env.PHONE_NUMBER_ID + "/messages";
 
async function sendWithPairBackoff(payload, attempt = 0) {
  const res = await fetch(URL, {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.ACCESS_TOKEN,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });
  if (res.ok) return res.json();
 
  const { error } = await res.json();
  if (error?.code === 131056 && attempt < 4) {
    // Meta's suggested schedule: wait 4^X seconds (1 s, 4 s, 16 s, 64 s),
    // plus up to 25% jitter so parallel workers don't retry in lockstep.
    const wait = 1_000 * 4 ** attempt * (1 + Math.random() * 0.25);
    await new Promise((r) => setTimeout(r, wait));
    return sendWithPairBackoff(payload, attempt + 1);
  }
  throw Object.assign(new Error(error?.message ?? "send failed"), { code: error?.code });
}
 
export function enqueue(payload) {
  const prev = queues.get(payload.to) ?? Promise.resolve();
  const next = prev.catch(() => {}).then(() => sendWithPairBackoff(payload));
  queues.set(payload.to, next);
  return next;
}

Messages to the same user go out in order, one at a time. Messages to other users never wait behind them.

Specifications

The pair rate limit: key facts and limits

Error code
131056
Scope
One business number to one WhatsApp user
Threshold
Set by Meta and tunable; don't hard-code it
Bursts
Tolerated, but they borrow from the pair's future allowance
Meta's retry schedule
4^X seconds: 1 s, 4 s, 16 s, 64 s…
Other recipients
Unaffected; keep sending to them
Often confused with
130429 (throughput), 131049 (per-user marketing limit)
Recommended response
Per-recipient backoff with jitter

Example: A chatbot that talked too fast

A Hyderabad coaching institute's admissions bot answered "What courses do you have?" with nine separate text bubbles sent back to back, one per course. Applicants who asked follow-ups straight away started seeing gaps, and the logs showed error 131056 on the later bubbles. The team replaced the nine bubbles with one interactive list message, and added a per-recipient queue that waits and retries on 131056. The failures stopped, and the same answer now costs one message instead of nine.

Failure modes

Common mistakes with the pair rate limit

  • Pausing the whole number on 131056

    The limit is per recipient. Throttling every send because one user tripped it delays thousands of unrelated conversations. Key your backoff on the recipient's WhatsApp ID.

  • Retrying immediately in a tight loop

    Instant retries keep the pair hot and make the throttling last longer. Wait with exponential backoff and jitter, and cap the number of retries.

  • Treating 131056 like 131049

    Error 131049 is the per-user marketing limit, where Meta advises waiting at least 24 hours before retrying. 131056 clears much sooner. Branch on the exact code, not on "some rate limit".

  • Splitting one answer into many bubbles

    Bots that send each paragraph as a separate message hit the pair limit. Since 1 October 2026, they also pay for every bubble in India. Combine the text, and use list or button messages.

Recommended practice

Best practices for the pair rate limit

  • Keep a send log for each recipient, so you can spot bursts before they become errors.
  • Add a short delay between automated messages in a sequence to the same user.
  • Watch failed status webhooks as well as API responses for code 131056.
  • Alert on the hourly rate of 131056 errors. A spike usually means a bot loop.

Pair Rate Limit FAQs

What does WhatsApp error 131056 mean?+
It means your business number sent too many messages to the same user in a short time. Wait and retry for that user. You can keep messaging other users without waiting, because the limit applies to one sender–recipient pair.
How many messages per second can I send to one WhatsApp user?+
There is no rate you should build to. Short bursts are tolerated but borrow from future allowance, sustained rapid sends are throttled, and Meta can tune the figures, so pace each recipient and back off on 131056 instead of hard-coding a rate.
Is the pair rate limit the same as throughput?+
No. Throughput caps the total messages per second from a number across all recipients, and returns 130429 when exceeded. The pair limit applies to one recipient and returns 131056.
Does upgrading to 1,000 messages per second remove the pair rate limit?+
No. The throughput upgrade raises the number's total sending capacity. The limit on rapid sends to a single user still applies, so per-recipient pacing is still needed.

See InfiQ pricing

Put Pair Rate Limit to work

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms