WhatsApp error 131057 (business account in maintenance mode): usually a throughput upgrade, here is what to do

WhatsApp error 131057 usually appears at a surprising moment: your number is doing well, sending heavily, and suddenly every request fails for about a minute. Meta's error codes page lists it as "Business Account is in maintenance mode" and explains: "The WhatsApp Business account is in maintenance mode. One reason for this could be that the account is undergoing a throughput upgrade." In most cases that is exactly what is happening, and the fix is to wait briefly and carry on.

Why a throughput upgrade causes 131057

Throughput is how many messages per second (mps) one business phone number can send. Meta's throughput page sets 80 mps by default and upgrades eligible numbers automatically to up to 1,000 mps. Eligibility needs an unlimited messaging limit and a quality rating of Medium or better.

The switch is not instant. Meta's words: "The upgrade process itself can take up to 1 minute. During this time the number will not be usable on our platform." If you call the API with that number during the upgrade, it returns 131057. When the upgrade is done, Meta sends a phone_number_quality_update webhook with event set to THROUGHPUT_UPGRADE, and after that, according to the same page, the number "will automatically be upgraded for any future throughput increases with no downtime".

So the timeline looks like this:

Other reasons for maintenance mode

Meta says a throughput upgrade is "one reason", not the only one. If 131057 lasts longer than a few minutes, or shows up on a number that was already upgraded, it is something else. In that case:

• Check the WhatsApp Business Platform Status page for an incident affecting the Cloud API.
• Open WhatsApp Manager and look at the phone number's status and any notices on the account.
• Query the account's health with the health_status field on the WhatsApp Business account ID, which shows whether sending is AVAILABLE, LIMITED or BLOCKED and why.
• Open a support ticket with Meta if it persists, quoting a few fbtrace_id values from the failures.

What the error looks like

Values, title and trace ID illustrative:

{
  "error": {
    "message": "(#131057) Account in maintenance mode",
    "type": "OAuthException",
    "code": 131057,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Business Account is in maintenance mode"
    },
    "fbtrace_id": "Ap7LcV2nXq0TmR4wKs9bYuF"
  }
}

And the webhook that tells you it is over (illustrative values, shape from Meta's throughput page):

{
  "field": "phone_number_quality_update",
  "value": {
    "display_phone_number": "919812345678",
    "event": "THROUGHPUT_UPGRADE",
    "max_daily_conversations_per_business": "TIER_UNLIMITED"
  }
}

How to handle it in code

1. Recognise 131057 as a short pause, not a failure of the message. The request was refused because the number was unavailable, not because the content was wrong.
2. Pause that number's queue for about 60 seconds instead of failing the remaining recipients one by one.
3. Retry with back-off: for example after 30, 60 and 120 seconds. Most upgrades clear within the first or second attempt.
4. Resume on the webhook if you have it. When the THROUGHPUT_UPGRADE event arrives, restart the queue straight away.
5. Escalate after a few minutes. If 131057 is still coming back after five minutes, treat it as one of the other reasons above.
6. Do not raise your send rate in the same minute. The new ceiling is available after the upgrade; ramp up gradually, as described in the 130429 rate limit guide.

A worked example

Rangoli Home, a home decor brand in Jaipur, has grown steadily over Navratri and reached an unlimited messaging limit with High quality. On the Sunday before Diwali, Arjun starts a 40,000-message festive campaign at 11 am. Ninety seconds in, about 3,000 sends fail with 131057 within one minute (illustrative numbers). Then the failures stop, and the rest of the campaign goes out normally.

A look at the webhook log shows a phone_number_quality_update event with THROUGHPUT_UPGRADE at 11:02. Nothing was wrong with the template or the list. Arjun retargets the 3,000 recipients that afternoon. For the next large campaign there is nothing to plan around: the number is already upgraded, so future increases happen without downtime.

Preventing lost sends

• Subscribe to phone_number_quality_update so your systems know when a number changes tier or throughput.
• Build pause-and-resume into your queue instead of marking each recipient failed on the first error.
• Expect the upgrade as numbers grow. A number that has just reached unlimited is the one most likely to see 131057 during its next big send.
• Keep one sender per number, so a pause in one integration does not leave another still hammering the API.

How Broadchat handles 131057

Broadchat does not retry 131057 automatically. A campaign recipient whose send fails with it is marked Failed with Meta's message as the reason, and a template that fails at Meta is not charged to the channel wallet. Once the minute has passed, open the campaign, filter by Failed and use Retarget to send those recipients a new campaign. If you call a channel's Graph-compatible API from your own code, the response is Meta's, unchanged, so you can apply the pause-and-retry pattern above.

For every other code see the WhatsApp API error codes cheat-sheet; for how tiers and quality work, WhatsApp messaging limits and tiers and the plain-English guide to the WhatsApp Business API. Agencies whose clients run large broadcasts can offer paced WhatsApp broadcasts under their own brand through the white-label program.