Waiting, errors and retries

A send is answered at once with 202 and status: "queued". The message then goes out the way a person would send it, so it may wait. A rule either holds it (it stays queued and goes by itself) or fails it (status: "failed", with the reason in error). This page says which is which, how long a wait can last, and what your code should try again.

Where to see why#

• A failed message says why in its error, in plain words: in GET /v1/messages/{id}, in the message.status webhook, and in your panel under the message in its chat and in the Message log (under Developers). Its error_code says the same as a fixed value for your code: see Error codes.
• A waiting message stays queued until it goes, with no error. Its error_code names what it is waiting for, and is null again once it has gone. GET /v1/instances/{id} shows where the instance stands today under protection: the day's limits and how much of them is used, its timezone, and under new_chats whether new chats are paused, why and until when.

What holds a message#

A held message needs nothing from you. It goes when its turn comes.

What fails a message#

A failed message will not go by itself. Read error: it says what to do.

• The instance cannot send: it is not connected, it is stopped, the account is suspended, or a different phone was linked after the message was queued.
• The person: they wrote "STOP", or their number is not on WhatsApp.
• The day's limits: the instance's new people for the day are used up, or its warm-up's daily messages that are not replies, or its group messages (200 a day) or channel posts (30 a day). The reason says "Try again tomorrow".
• Someone new who has not answered: more than 2 follow-ups in a day, or a new first message before 7 days have passed. The reason gives the date it may go.
• What a first message holds: a location, a contact card, a sticker or a poll; an http:// link, or only a link; more than 600 characters; or a text or file that already opened 5 chats that day.
• New chats are paused: by WhatsApp for longer than 6 hours, by us, or because almost nobody answers the instance's first messages. Replies still go.
• The file: it could not be fetched, is too large, or a sticker is not a WebP image.
• WhatsApp refused it, or did not confirm it in time. In the second case it may have been delivered: look at the chat before sending it again.
• An OTP code that cannot go within 2 minutes fails at once: a late code is useless.
• You cancelled it before it went.

The rules themselves are in How sending protects your number.

A message's error codes#

error is written for people, and its words may change. error_code is for your code: one fixed value per reason, on the message in the API and in the message.status event. On a failed message it is why it failed. On a queued one it is what the message is waiting for, and no event is sent for a wait. A message that failed before codes were added has none. New values may be added, so treat one you do not know like error alone.

A message that "waits" fails with the same code when the wait cannot end in time: see The longest wait. A request the API refuses outright (409, 422, 429) makes no message, so it has no error_code: read its message.

The longest wait#

A message waits at most 24 hours, counted from when you sent it, or from its send_at if you scheduled it. A hold that would last to within 10 minutes of that is not started: the message fails then, and its error names what held it, usually ending "It waited as long as it could, so it was not sent. Send it again if it is still wanted." One still queued when the 24 hours end fails with "Could not reach WhatsApp. Please try again.", or with a note that it may have been delivered.

The pace#

Each instance sends one message at a time. After any message, the next one waits a gap, picked at random, by who it is for:

A message to a person or a group also shows "typing…" for 1 to 4 seconds first. Above all of this there is a ceiling of 20 messages a minute per instance. So 100 replies take ten to fifteen minutes. 100 first messages take days: a newly linked instance may message 10 new people a day, rising to 50 over its first two weeks.

Different instances send at the same time; one does not slow another.

Do not send faster than an instance sends. The API takes 600 requests a minute, and an instance sends about 20 messages a minute, so a burst only makes a queue. Once an instance has more than 500 messages waiting or scheduled, POST /v1/messages to it answers 429 with the code backlog_full and a Retry-After: send the rest as these go out. Messages scheduled with send_at count like the waiting ones. Replies to people who wrote in the last 24 hours are always taken. For one message to many people, use a broadcast, which paces itself.

What your code should retry#

A request that was refused (no message was made):

Send the same Idempotency-Key on every retry of one message, so two answers to one request can never become two messages. POST /v1/otps and POST /v1/broadcasts take the header too.

A message that was accepted (202) needs no retry while it is queued: waiting is normal.

A message that failed: never send it again in a loop. Repeating a refused message is the pattern WhatsApp bans, and the same reason will refuse it again. Read error and act on it: wait for tomorrow, let the person write first, fix the file. When you do send it again, use a new Idempotency-Key: the old key returns the failed message.

The API's error codes#

A refused request carries a code beside its message. We may improve a message's words; a code never changes. So let your program act on the code, and show or log the message.