Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(api): describe the Baileys throttle 503

Yudhi Armyndharis982268cb8fcb
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index db245990d..110d74b88 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -1524,7 +1524,7 @@ Pin a message in its chat for a bounded window.
**Response** `200` — `{ "success": true }`
-**Errors:** `400` session not active, or `durationSeconds` outside the three accepted values · `401` missing/invalid API key · `403` the whatsapp-web.js engine refused the pin (in a group only admins may pin; the Baileys engine has no acceptance signal and answers `200`) · `404` message not found in the chat · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; a retry is safe but restarts the pin duration; on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe)
+**Errors:** `400` session not active, or `durationSeconds` outside the three accepted values · `401` missing/invalid API key · `403` the whatsapp-web.js engine refused the pin (in a group only admins may pin; the Baileys engine has no acceptance signal and answers `200`) · `404` message not found in the chat · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; a retry is safe but restarts the pin duration; on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe), or when WhatsApp rate-limited the request (code 429: nothing was sent) or timed out a query it awaits (code 408: the outcome is not proven)
> On whatsapp-web.js the message must be within the 100-message fetch window for the chat, the same
> limit that applies to react/delete/edit. On Baileys it must be in the adapter's message store.
@@ -1568,7 +1568,7 @@ Remove a message's pin. Takes no duration.
**Response** `200` — `{ "success": true }`
-**Errors:** `400` session not active · `401` missing/invalid API key · `403` the whatsapp-web.js engine refused the unpin (in a group only admins may unpin; the Baileys engine has no acceptance signal and answers `200`) · `404` message not found in the chat · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; repeating it is safe (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe)
+**Errors:** `400` session not active · `401` missing/invalid API key · `403` the whatsapp-web.js engine refused the unpin (in a group only admins may unpin; the Baileys engine has no acceptance signal and answers `200`) · `404` message not found in the chat · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; repeating it is safe (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe), or when WhatsApp rate-limited the request (code 429: nothing was sent) or timed out a query it awaits (code 408: the outcome is not proven)
#### GET /api/sessions/:sessionId/messages/:chatId/:messageId/media
@@ -1821,7 +1821,7 @@ rejected with `400` rather than guessing which half was meant.
`messageId` is the WhatsApp message id from the engine. By default (`SIMULATE_TYPING`; set it to `false` to disable) a typing indicator and a humanising pause run before the send: 500 ms plus 45 ms per character, capped at `SIMULATE_TYPING_MAX_MS` (default 5000 ms), with +/-15% jitter.
-**Errors:** `400` unknown body field, validation failure, or session not active / blocked by a plugin hook · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent
+**Errors:** `400` unknown body field, validation failure, or session not active / blocked by a plugin hook · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent, or WhatsApp rate-limited the send (code 429: nothing was sent, the `Idempotency-Key` is freed) or timed out a query it awaits (code 408: the outcome is not proven, the key stays taken)
##### Quoted sends
@@ -1910,7 +1910,7 @@ Render a stored text template (header/body/footer joined by blank lines, `{{vars
Delegates to the send-text path after rendering.
-**Errors:** `400` unknown body field, validation failure, neither `templateId` nor `templateName` given, or session not active · `401` missing/invalid API key · `403` key role below OPERATOR · `404` session or template not found · `500` engine error · `409` conflict or engine not ready (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent
+**Errors:** `400` unknown body field, validation failure, neither `templateId` nor `templateName` given, or session not active · `401` missing/invalid API key · `403` key role below OPERATOR · `404` session or template not found · `500` engine error · `409` conflict or engine not ready (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent, or WhatsApp rate-limited the send (code 429: nothing was sent, the `Idempotency-Key` is freed) or timed out a query it awaits (code 408: the outcome is not proven, the key stays taken)
#### POST /api/sessions/:sessionId/messages/send-image
@@ -1947,7 +1947,7 @@ Send an image (by URL or base64) with an optional caption.
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` neither `url` nor `base64`, base64 without `mimetype`, SSRF-blocked URL, a `url` that answers non-2xx, times out or cannot be reached, session not active, or unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
+**Errors:** `400` neither `url` nor `base64`, base64 without `mimetype`, SSRF-blocked URL, a `url` that answers non-2xx, times out or cannot be reached, session not active, or unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe), or when WhatsApp rate-limited the send (code 429: nothing was sent, the `Idempotency-Key` is freed) or timed out a query it awaits (code 408: the outcome is not proven, the key stays taken) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-video
@@ -1973,7 +1973,7 @@ Send a video (by URL or base64) with an optional caption. Uses the same `SendMed
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
+**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe), or when WhatsApp rate-limited the send (code 429: nothing was sent, the `Idempotency-Key` is freed) or timed out a query it awaits (code 408: the outcome is not proven, the key stays taken) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-audio
@@ -1999,7 +1999,7 @@ Send an audio message (by URL or base64). Uses `SendAudioMessageDto`. A `caption
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
+**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe), or when WhatsApp rate-limited the send (code 429: nothing was sent, the `Idempotency-Key` is freed) or timed out a query it awaits (code 408: the outcome is not proven, the key stays taken) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-document
@@ -2032,7 +2032,7 @@ Send a document/file (by URL or base64). Uses `SendMediaMessageDto`; `filename`
**Engine differences:** Baileys always sends a document as a document, while whatsapp-web.js deliberately keeps normal mimetype classification for `status@broadcast` and broadcast lists; the library returns `null` for document-mode sends to those recipients, so forcing the flag there would turn a working send into a failure. For URL-based sends without an explicit `filename`, whatsapp-web.js derives the URL basename, percent-decoded; Baileys falls back to the literal `file`.
-**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
+**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe), or when WhatsApp rate-limited the send (code 429: nothing was sent, the `Idempotency-Key` is freed) or timed out a query it awaits (code 408: the outcome is not proven, the key stays taken) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-location
@@ -2073,7 +2073,7 @@ Send a location pin.
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` invalid coords / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a location to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent
+**Errors:** `400` invalid coords / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a location to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent, or WhatsApp rate-limited the send (code 429: nothing was sent, the `Idempotency-Key` is freed) or timed out a query it awaits (code 408: the outcome is not proven, the key stays taken)
#### POST /api/sessions/:sessionId/messages/send-contact
@@ -2106,7 +2106,7 @@ Send a contact card (vCard).
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a contact card to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent
+**Errors:** `400` validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a contact card to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent, or WhatsApp rate-limited the send (code 429: nothing was sent, the `Idempotency-Key` is freed) or timed out a query it awaits (code 408: the outcome is not proven, the key stays taken)
#### POST /api/sessions/:sessionId/messages/send-sticker
@@ -2132,7 +2132,7 @@ Send a sticker (by URL or base64; typically webp). Reuses `SendMediaMessageDto`.
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` media validation failure / (Baileys) media that is neither WebP nor an image that converts to one, or an animation with more than 500 frames / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field; on Baileys, also a phone number WhatsApp reports as unregistered · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine, or (whatsapp-web.js) a sticker to a channel, `status@broadcast` or a broadcast list · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
+**Errors:** `400` media validation failure / (Baileys) media that is neither WebP nor an image that converts to one, or an animation with more than 500 frames / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field; on Baileys, also a phone number WhatsApp reports as unregistered · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine, or (whatsapp-web.js) a sticker to a channel, `status@broadcast` or a broadcast list · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe), or when WhatsApp rate-limited the send (code 429: nothing was sent, the `Idempotency-Key` is freed) or timed out a query it awaits (code 408: the outcome is not proven, the key stays taken) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))
#### POST /api/sessions/:sessionId/messages/send-poll
@@ -2171,7 +2171,7 @@ Send a native WhatsApp poll.
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Errors:** `400` validation failure (option count/length) / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a poll to a status or broadcast list (`@broadcast`), nor one with `quotedMessageId` to a channel (`<id>@newsletter`); nothing is sent · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent
+**Errors:** `400` validation failure (option count/length) / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a poll to a status or broadcast list (`@broadcast`), nor one with `quotedMessageId` to a channel (`<id>@newsletter`); nothing is sent · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent, or WhatsApp rate-limited the send (code 429: nothing was sent, the `Idempotency-Key` is freed) or timed out a query it awaits (code 408: the outcome is not proven, the key stays taken)
#### POST /api/sessions/:sessionId/messages/reply
@@ -2206,7 +2206,7 @@ Reply to a message, quoting a prior message.
The quoted body is best-effort resolved from the DB for the reply preview.
-**Errors:** `400` validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the quoted message is not found in this chat · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a reply to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent
+**Errors:** `400` validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the quoted message is not found in this chat · `500` engine error · `409` conflict or engine not ready (retryable) · `501` whatsapp-web.js cannot send a reply to a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`); nothing is sent · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent, or WhatsApp rate-limited the send (code 429: nothing was sent, the `Idempotency-Key` is freed) or timed out a query it awaits (code 408: the outcome is not proven, the key stays taken)
#### POST /api/sessions/:sessionId/messages/click-button
@@ -2249,7 +2249,7 @@ Tap a choice on a WhatsApp Business button / list prompt by sending the structur
> render after the store evicts the prompt, and a tap then 404s. URL/call CTA buttons cannot be
> clicked this way, only quick-reply style choices and list rows.
-**Errors:** `400` validation failure, session not active, the message is not a clickable prompt, or `buttonId` is not among its choices · `401` · `403` · `404` prompt not in the engine store / wrong chat · `501` whatsapp-web.js · `409` conflict or engine not ready (retryable) · `500` engine error · `503` Baileys recipient lookup failed or timed out before the operation was sent
+**Errors:** `400` validation failure, session not active, the message is not a clickable prompt, or `buttonId` is not among its choices · `401` · `403` · `404` prompt not in the engine store / wrong chat · `501` whatsapp-web.js · `409` conflict or engine not ready (retryable) · `500` engine error · `503` Baileys recipient lookup failed or timed out before the operation was sent, or WhatsApp rate-limited the send (code 429: nothing was sent) or timed out a query it awaits (code 408: the outcome is not proven)
#### POST /api/sessions/:sessionId/messages/forward
@@ -2283,7 +2283,7 @@ Forward a message from one chat to another.
`messageId` may be an empty string when the engine could not recover the forwarded copy's id.
-**Errors:** `400` validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the message to forward is not found in `fromChatId` · `500` engine error · `409` conflict or engine not ready (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent
+**Errors:** `400` validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the message to forward is not found in `fromChatId` · `500` engine error · `409` conflict or engine not ready (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends)) · `503` Baileys recipient lookup failed or timed out before the operation was sent, or WhatsApp rate-limited the send (code 429: nothing was sent, the `Idempotency-Key` is freed) or timed out a query it awaits (code 408: the outcome is not proven, the key stays taken)
#### POST /api/sessions/:sessionId/messages/react
@@ -2317,7 +2317,7 @@ The controller hardcodes the result after the engine call. Note the `200` status
{ "success": true }
```
-**Errors:** `400` session not active, or an invalid request (an unknown body field or a value of the wrong type) · `401` missing/invalid API key · `403` key role below OPERATOR · `404` message not found in this chat · `500` engine error · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; repeating it is safe (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe)
+**Errors:** `400` session not active, or an invalid request (an unknown body field or a value of the wrong type) · `401` missing/invalid API key · `403` key role below OPERATOR · `404` message not found in this chat · `500` engine error · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; repeating it is safe (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe), or when WhatsApp rate-limited the request (code 429: nothing was sent) or timed out a query it awaits (code 408: the outcome is not proven)
#### POST /api/sessions/:sessionId/messages/delete
@@ -2351,7 +2351,7 @@ After the engine delete, the stored message's body and `metadata` (inline media,
{ "success": true }
```
-**Errors:** `400` session not active, or an invalid request (an unknown body field or a value of the wrong type) · `401` missing/invalid API key · `403` key role below OPERATOR · `404` message not found in this chat · `500` engine error · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe)
+**Errors:** `400` session not active, or an invalid request (an unknown body field or a value of the wrong type) · `401` missing/invalid API key · `403` key role below OPERATOR · `404` message not found in this chat · `500` engine error · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe), or when WhatsApp rate-limited the request (code 429: nothing was sent) or timed out a query it awaits (code 408: the outcome is not proven)
#### POST /api/sessions/:sessionId/messages/edit
@@ -2386,7 +2386,7 @@ Both fields describe the edited message rather than the edit itself, on both eng
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1760000000 }
```
-**Errors:** `400` session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR, or the engine refused the edit (both engines refuse a message the account did not send; whatsapp-web.js also refuses one that is not text, where the Baileys engine has no acceptance signal and answers `200`) · `404` message not found · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; repeating it is safe (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe)
+**Errors:** `400` session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR, or the engine refused the edit (both engines refuse a message the account did not send; whatsapp-web.js also refuses one that is not text, where the Baileys engine has no acceptance signal and answers `200`) · `404` message not found · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; repeating it is safe (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe), or when WhatsApp rate-limited the request (code 429: nothing was sent) or timed out a query it awaits (code 408: the outcome is not proven)
#### POST /api/sessions/:sessionId/messages/send-bulk
@@ -3812,7 +3812,7 @@ Send a product message (catalog product card) to a chat. Note: this route lives
**Response** `201` (Baileys engine only) — the sent `MessageResult`
-**Errors:** `400` missing or empty `chatId`/`productId`, a `productId` over 255 or a `body` over 4096 characters, wrong types, any field not on the DTO, a product with no image (a product card needs one), or a `message:sending` plugin blocked the send or returned an invalid `productId`/`body`; on Baileys, also a phone number WhatsApp reports as unregistered · `401` missing/invalid API key · `403` API-key role below OPERATOR, or WhatsApp refused the catalog query · `404` `Session <sessionId> not found or not connected`, or the product is not in the session catalog · `409` session present but not READY (retryable) · `500` engine error · `501` whatsapp-web.js only (no Catalog API) · `503` the catalog query went unanswered or was rate-limited by WhatsApp, or the session/dependency is not ready (a rate limit or the not-ready case can clear on retry; a silently unanswered catalog query does not); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe)
+**Errors:** `400` missing or empty `chatId`/`productId`, a `productId` over 255 or a `body` over 4096 characters, wrong types, any field not on the DTO, a product with no image (a product card needs one), or a `message:sending` plugin blocked the send or returned an invalid `productId`/`body`; on Baileys, also a phone number WhatsApp reports as unregistered · `401` missing/invalid API key · `403` API-key role below OPERATOR, or WhatsApp refused the catalog query · `404` `Session <sessionId> not found or not connected`, or the product is not in the session catalog · `409` session present but not READY (retryable) · `500` engine error · `501` whatsapp-web.js only (no Catalog API) · `503` the catalog query went unanswered or was rate-limited by WhatsApp, or the session/dependency is not ready (a rate limit or the not-ready case can clear on retry; a silently unanswered catalog query does not); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe), or when WhatsApp rate-limited the request (code 429: nothing was sent) or timed out a query it awaits (code 408: the outcome is not proven)
On whatsapp-web.js the readiness guard runs before the refusal, so a session that exists but is not
`READY` gets `409` instead of `501`. Baileys resolves the product from the session catalog and sends
@@ -4438,7 +4438,7 @@ Returns the engine `StatusResult` directly (no wrapper). POST default status is
**Sender-side caveat:** the posting account's own phone may display a "waiting for this status update" notice in its status feed; this is cosmetic — recipients view the status normally.
-**Errors:** `400` validation failure (unknown body field, a JID not matching `@c.us`/`@lid`, more than 256 recipients, `text` over 4096 chars, bad `backgroundColor`/`font`), or (Baileys) no `recipients`, or the post was blocked by a plugin · `401` missing/invalid API key · `403` key lacks `OPERATOR` role · `404` session not found / not connected · `409` conflict or engine not ready (retryable)
+**Errors:** `400` validation failure (unknown body field, a JID not matching `@c.us`/`@lid`, more than 256 recipients, `text` over 4096 chars, bad `backgroundColor`/`font`), or (Baileys) no `recipients`, or the post was blocked by a plugin · `401` missing/invalid API key · `403` key lacks `OPERATOR` role · `404` session not found / not connected · `409` conflict or engine not ready (retryable) · `503` on Baileys, WhatsApp rate-limited the post (code 429: nothing was posted) or timed out a query it awaits (code 408: the outcome is not proven)
#### POST /api/sessions/:sessionId/status/send-image
@@ -4487,7 +4487,7 @@ Returns the engine `StatusResult` directly. POST default status is `201`.
**Recipient JIDs:** `@c.us` (regular phone) recipients are reliable. `@lid` (privacy-id) recipients are best-effort and unverified — prefer `@c.us` where the phone number is known. **Sender-side caveat:** the posting account's own phone may show a "waiting for this status update" notice; recipients view it normally.
-**Errors:** `400` validation failure (unknown body field, an empty media wrapper, a JID not matching `@c.us`/`@lid`, more than 256 recipients, or a caption over 1024 chars), or a `url` that answers non-2xx, times out or cannot be reached, or (Baileys) no `recipients`, or the post was blocked by a plugin · `401` missing/invalid API key · `403` key lacks `OPERATOR` role · `404` session not found / not connected · `409` conflict or engine not ready (retryable) · `413` base64 or downloaded media over the media cap (see §6.3) · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable)
+**Errors:** `400` validation failure (unknown body field, an empty media wrapper, a JID not matching `@c.us`/`@lid`, more than 256 recipients, or a caption over 1024 chars), or a `url` that answers non-2xx, times out or cannot be reached, or (Baileys) no `recipients`, or the post was blocked by a plugin · `401` missing/invalid API key · `403` key lacks `OPERATOR` role · `404` session not found / not connected · `409` conflict or engine not ready (retryable) · `413` base64 or downloaded media over the media cap (see §6.3) · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when WhatsApp rate-limited the post (code 429: nothing was posted) or timed out a query it awaits (code 408: the outcome is not proven)
#### POST /api/sessions/:sessionId/status/send-video
@@ -4536,7 +4536,7 @@ Returns the engine `StatusResult` directly. POST default status is `201`.
**Recipient JIDs:** `@c.us` (regular phone) recipients are reliable. `@lid` (privacy-id) recipients are best-effort and unverified — prefer `@c.us` where the phone number is known. **Sender-side caveat:** the posting account's own phone may show a "waiting for this status update" notice; recipients view it normally.
-**Errors:** `400` validation failure (unknown body field, an empty media wrapper, a JID not matching `@c.us`/`@lid`, more than 256 recipients, or a caption over 1024 chars), or a `url` that answers non-2xx, times out or cannot be reached, or (Baileys) no `recipients`, or the post was blocked by a plugin · `401` missing/invalid API key · `403` key lacks `OPERATOR` role · `404` session not found / not connected · `409` conflict or engine not ready (retryable) · `413` base64 or downloaded media over the media cap (see §6.3) · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable)
+**Errors:** `400` validation failure (unknown body field, an empty media wrapper, a JID not matching `@c.us`/`@lid`, more than 256 recipients, or a caption over 1024 chars), or a `url` that answers non-2xx, times out or cannot be reached, or (Baileys) no `recipients`, or the post was blocked by a plugin · `401` missing/invalid API key · `403` key lacks `OPERATOR` role · `404` session not found / not connected · `409` conflict or engine not ready (retryable) · `413` base64 or downloaded media over the media cap (see §6.3) · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when WhatsApp rate-limited the post (code 429: nothing was posted) or timed out a query it awaits (code 408: the outcome is not proven)
#### POST /api/sessions/:sessionId/status/send-voice
@@ -4573,7 +4573,7 @@ There is **no `caption`**: WhatsApp has nowhere to render one on a status voice
**Read-back:** a voice status is listed with `"type": "voice"`. That member was added with this endpoint; before it, anything that was not an image or a video was reported as `text`.
-**Errors:** `400` validation failure, neither `url` nor `base64` supplied, or a `url` that answers non-2xx, times out or cannot be reached, or (Baileys) no `recipients`, or the post was blocked by a plugin · `401` missing/invalid API key · `403` key lacks `OPERATOR` role · `404` session not found / not connected · `413` base64 or downloaded media exceeds `MEDIA_DOWNLOAD_MAX_BYTES` · `409` conflict or engine not ready (retryable) · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable)
+**Errors:** `400` validation failure, neither `url` nor `base64` supplied, or a `url` that answers non-2xx, times out or cannot be reached, or (Baileys) no `recipients`, or the post was blocked by a plugin · `401` missing/invalid API key · `403` key lacks `OPERATOR` role · `404` session not found / not connected · `413` base64 or downloaded media exceeds `MEDIA_DOWNLOAD_MAX_BYTES` · `409` conflict or engine not ready (retryable) · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when WhatsApp rate-limited the post (code 429: nothing was posted) or timed out a query it awaits (code 408: the outcome is not proven)
#### DELETE /api/sessions/:sessionId/status/:id
@@ -4596,7 +4596,7 @@ Delete one of the session's own posted statuses.
The service returns `void`; the controller returns a fixed success object. DELETE default status is `200`.
-**Errors:** `401` missing/invalid API key · `403` key lacks `OPERATOR` role, or (whatsapp-web.js) the id is not one of the account's own statuses, or (Baileys) this session did not post the status in the last 24 hours, so its recipients are unknown (a status posted from the phone or from another node, or before this session's engine was last created, is refused too: a process restart, a session stop and start, and a reconnect the gateway runs itself, such as after a failed liveness check, each create a new one) · `404` `Session {id} not found or not connected` · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request, so the revoke did not complete
+**Errors:** `401` missing/invalid API key · `403` key lacks `OPERATOR` role, or (whatsapp-web.js) the id is not one of the account's own statuses, or (Baileys) this session did not post the status in the last 24 hours, so its recipients are unknown (a status posted from the phone or from another node, or before this session's engine was last created, is refused too: a process restart, a session stop and start, and a reconnect the gateway runs itself, such as after a failed liveness check, each create a new one) · `404` `Session {id} not found or not connected` · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request, so the revoke did not complete; on Baileys, also when WhatsApp rate-limits the revoke (code 429) or times out a query it awaits (code 408)
Safe to retry: revoking an already-revoked status converges. The status POST routes deliberately do
NOT answer `503` for the same failure, because whatsapp-web.js can throw after the request is on the
diff --git a/openapi.json b/openapi.json
index 9b8c90a06..2607f94c4 100644
--- a/openapi.json
+++ b/openapi.json
@@ -4531,7 +4531,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -4652,7 +4652,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -4803,7 +4803,7 @@
}
},
"503": {
- "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -4953,7 +4953,7 @@
}
},
"503": {
- "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -5104,7 +5104,7 @@
}
},
"503": {
- "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -5255,7 +5255,7 @@
}
},
"503": {
- "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -5397,7 +5397,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -5538,7 +5538,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -5688,7 +5688,7 @@
}
},
"503": {
- "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -5832,7 +5832,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -5963,7 +5963,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -6076,7 +6076,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -6197,7 +6197,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
@@ -6299,7 +6299,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. The whatsapp-web.js page connection died mid-request. The change may or may not have been applied; repeating the request is safe, since it converges on the same state.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken). The whatsapp-web.js page connection died mid-request. The change may or may not have been applied; repeating the request is safe, since it converges on the same state.",
"content": {
"application/json": {
"schema": {
@@ -6889,7 +6889,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. WhatsApp did not answer within the request budget. The change may or may not have been applied — the gateway stopped waiting for a confirmation that never came.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken). WhatsApp did not answer within the request budget. The change may or may not have been applied — the gateway stopped waiting for a confirmation that never came.",
"content": {
"application/json": {
"schema": {
@@ -7103,7 +7103,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. The whatsapp-web.js page connection died mid-request. The pin may or may not have been applied; a retry is safe, but it restarts the pin duration from the moment it succeeds.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken). The whatsapp-web.js page connection died mid-request. The pin may or may not have been applied; a retry is safe, but it restarts the pin duration from the moment it succeeds.",
"content": {
"application/json": {
"schema": {
@@ -7205,7 +7205,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. The whatsapp-web.js page connection died mid-request. The change may or may not have been applied; repeating the request is safe, since it converges on the same state.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken). The whatsapp-web.js page connection died mid-request. The change may or may not have been applied; repeating the request is safe, since it converges on the same state.",
"content": {
"application/json": {
"schema": {
@@ -7409,7 +7409,7 @@
}
},
"503": {
- "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. The whatsapp-web.js page connection died mid-request. The change may or may not have been applied; repeating the request is safe, since it converges on the same state.",
+ "description": "Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken). The whatsapp-web.js page connection died mid-request. The change may or may not have been applied; repeating the request is safe, since it converges on the same state.",
"content": {
"application/json": {
"schema": {
@@ -14715,7 +14715,7 @@
}
},
"503": {
- "description": "The whatsapp-web.js page connection died mid-request, so the revoke did not complete. Safe to retry: revoking an already-revoked status converges. The status POST routes deliberately do NOT answer this, because a replayed post would publish the status a second time.",
+ "description": "The whatsapp-web.js page connection died mid-request, so the revoke did not complete. Safe to retry: revoking an already-revoked status converges. The status POST routes deliberately do NOT answer this for whatsapp-web.js, because a replayed post would publish the status a second time. On Baileys, also when WhatsApp rate-limits the revoke (code 429) or times out a query it awaits (code 408).",
"content": {
"application/json": {
"schema": {
@@ -14884,6 +14884,16 @@
}
}
}
+ },
+ "503": {
+ "description": "On Baileys, WhatsApp can answer the post with a 503: it rate-limited the request (code 429: nothing was posted) or timed out a query the post awaits (code 408: the outcome is not proven, so the post may have been published).",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
}
},
"summary": "Post a text status",
@@ -14987,7 +14997,7 @@
}
},
"503": {
- "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`.",
+ "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. On Baileys, WhatsApp can answer the post with a 503: it rate-limited the request (code 429: nothing was posted) or timed out a query the post awaits (code 408: the outcome is not proven, so the post may have been published).",
"content": {
"application/json": {
"schema": {
@@ -15098,7 +15108,7 @@
}
},
"503": {
- "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`.",
+ "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. On Baileys, WhatsApp can answer the post with a 503: it rate-limited the request (code 429: nothing was posted) or timed out a query the post awaits (code 408: the outcome is not proven, so the post may have been published).",
"content": {
"application/json": {
"schema": {
@@ -15209,7 +15219,7 @@
}
},
"503": {
- "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`.",
+ "description": "The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy works points at the `url`. Without a session proxy the same failure answers `400`. On Baileys, WhatsApp can answer the post with a 503: it rate-limited the request (code 429: nothing was posted) or timed out a query the post awaits (code 408: the outcome is not proven, so the post may have been published).",
"content": {
"application/json": {
"schema": {
@@ -15869,7 +15879,7 @@
}
},
"503": {
- "description": "WhatsApp did not answer the catalog query within the request budget, or rate-limited it. For some business accounts WhatsApp never answers it, so a retry may not help. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure.",
+ "description": "WhatsApp did not answer the catalog query within the request budget, or rate-limited it. For some business accounts WhatsApp never answers it, so a retry may not help. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its `Idempotency-Key` taken).",
"content": {
"application/json": {
"schema": {
diff --git a/src/common/openapi/engine-status-responses.ts b/src/common/openapi/engine-status-responses.ts
index c2ec06eb7..4ea3d9632 100644
--- a/src/common/openapi/engine-status-responses.ts
+++ b/src/common/openapi/engine-status-responses.ts
@@ -99,6 +99,32 @@ export const RECIPIENT_LOOKUP_503 =
'Baileys could not complete the recipient lookup within the request budget. On send routes, ' +
'no message was handed to WhatsApp for this lookup failure.';
+/**
+ * `EngineThrottledError` (429) and `EngineTransportError` (408), both 503, from `mapSendRefusal`: on Baileys a
+ * send, reaction, delete, pin, edit or status post awaits several queries before it relays the message, and
+ * WhatsApp turns a throttled or timed out one away with that code. They differ in what they prove: a throttle
+ * sent nothing, so the idempotency key is freed; a timeout proves nothing, so the key stays taken.
+ */
+const SEND_REFUSAL_503 =
+ 'On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees ' +
+ 'its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed ' +
+ 'send keeps its `Idempotency-Key` taken).';
+
+/**
+ * Both texts, for every route that reaches the Baileys send path. `presence/subscribe` shares the recipient
+ * lookup but sends nothing, so it keeps RECIPIENT_LOOKUP_503 alone.
+ */
+export const SEND_503 = `${RECIPIENT_LOOKUP_503} ${SEND_REFUSAL_503}`;
+
+/**
+ * The same two refusals on a Baileys status post. It has no recipient to look up and takes no idempotency key,
+ * so the text names the post only.
+ */
+export const STATUS_POST_503 =
+ 'On Baileys, WhatsApp can answer the post with a 503: it rate-limited the request (code 429: nothing was ' +
+ 'posted) or timed out a query the post awaits (code 408: the outcome is not proven, so the post may have ' +
+ 'been published).';
+
/** `MessageNotFoundError` (404): outside the adapter's lookup window, or revoked. */
export const MESSAGE_NOT_FOUND_404 =
"No such message: the id is outside the engine's lookup window (roughly the last hundred messages " +
diff --git a/src/modules/catalog/catalog.controller.ts b/src/modules/catalog/catalog.controller.ts
index 3907a39de..a97856a61 100644
--- a/src/modules/catalog/catalog.controller.ts
+++ b/src/modules/catalog/catalog.controller.ts
@@ -5,11 +5,7 @@ import { SendProductDto, ProductQueryDto } from './dto/send-product.dto';
import { ChatScoped, RequireRole } from '../auth/decorators/auth.decorators';
import { ApiKeyRole } from '../auth/entities/api-key.entity';
import { CatalogDto, PaginatedProductsDto, ProductDto, ProductMessageResponseDto } from './dto/catalog-response.dto';
-import {
- ENGINE_NOT_READY_409,
- RECIPIENT_LOOKUP_503,
- SESSION_NOT_STARTED_404,
-} from '../../common/openapi/engine-status-responses';
+import { ENGINE_NOT_READY_409, SEND_503, SESSION_NOT_STARTED_404 } from '../../common/openapi/engine-status-responses';
/**
* Every catalog read walks WhatsApp's business-catalog IQ, which the server simply leaves
@@ -102,7 +98,7 @@ export class CatalogController {
})
@ApiResponse({ status: 403, description: CATALOG_REFUSED_403 })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
- @ApiResponse({ status: 503, description: `${CATALOG_TIMEOUT_503} ${RECIPIENT_LOOKUP_503}` })
+ @ApiResponse({ status: 503, description: `${CATALOG_TIMEOUT_503} ${SEND_503}` })
async sendProduct(@Param('sessionId') sessionId: string, @Body() dto: SendProductDto) {
return this.catalogService.sendProduct(sessionId, dto.chatId, dto.productId, dto.body);
}
diff --git a/src/modules/message/message.controller.ts b/src/modules/message/message.controller.ts
index 7f45ded34..38efc2c42 100644
--- a/src/modules/message/message.controller.ts
+++ b/src/modules/message/message.controller.ts
@@ -61,7 +61,7 @@ import {
MESSAGE_NOT_FOUND_404,
QUOTED_MESSAGE_NOT_FOUND_404,
RECIPIENT_UNREACHABLE_400,
- RECIPIENT_LOOKUP_503,
+ SEND_503,
} from '../../common/openapi/engine-status-responses';
import { IdempotentSend } from './idempotency/idempotent-send.decorator';
@@ -219,7 +219,7 @@ export class MessageController {
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 404, description: QUOTED_MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 501, description: `${CUSTOM_LINK_PREVIEW_501} ${QUOTED_SEND_501}` })
- @ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
+ @ApiResponse({ status: 503, description: SEND_503 })
async sendText(@Param('sessionId') sessionId: string, @Body() dto: SendTextMessageDto): Promise<MessageResponseDto> {
return this.messageService.sendText(sessionId, dto);
}
@@ -241,7 +241,7 @@ export class MessageController {
})
@ApiResponse({ status: 404, description: 'Template not found' })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
- @ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
+ @ApiResponse({ status: 503, description: SEND_503 })
async sendTemplate(
@Param('sessionId') sessionId: string,
@Body() dto: SendTemplateMessageDto,
@@ -271,7 +271,7 @@ export class MessageController {
@ApiResponse({ status: 404, description: QUOTED_MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 501, description: `${CHANNEL_MEDIA_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
- @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${RECIPIENT_LOOKUP_503}` })
+ @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${SEND_503}` })
async sendImage(
@Param('sessionId') sessionId: string,
@Body() dto: SendMediaMessageDto,
@@ -299,7 +299,7 @@ export class MessageController {
@ApiResponse({ status: 404, description: QUOTED_MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 501, description: `${CHANNEL_MEDIA_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
- @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${RECIPIENT_LOOKUP_503}` })
+ @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${SEND_503}` })
async sendVideo(
@Param('sessionId') sessionId: string,
@Body() dto: SendMediaMessageDto,
@@ -327,7 +327,7 @@ export class MessageController {
@ApiResponse({ status: 404, description: QUOTED_MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 501, description: `${CHANNEL_MEDIA_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
- @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${RECIPIENT_LOOKUP_503}` })
+ @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${SEND_503}` })
async sendAudio(
@Param('sessionId') sessionId: string,
@Body() dto: SendAudioMessageDto,
@@ -355,7 +355,7 @@ export class MessageController {
@ApiResponse({ status: 404, description: QUOTED_MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 501, description: `${CHANNEL_MEDIA_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
- @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${RECIPIENT_LOOKUP_503}` })
+ @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${SEND_503}` })
async sendDocument(
@Param('sessionId') sessionId: string,
@Body() dto: SendMediaMessageDto,
@@ -381,7 +381,7 @@ export class MessageController {
@ApiResponse({ status: 404, description: QUOTED_MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
@ApiResponse({ status: 501, description: wwebjsRefuses501(`a location to ${CHANNEL_OR_BROADCAST}`) })
- @ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
+ @ApiResponse({ status: 503, description: SEND_503 })
async sendLocation(@Param('sessionId') sessionId: string, @Body() dto: SendLocationDto): Promise<MessageResponseDto> {
return this.messageService.sendLocation(sessionId, dto);
}
@@ -402,7 +402,7 @@ export class MessageController {
@ApiResponse({ status: 404, description: QUOTED_MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
@ApiResponse({ status: 501, description: wwebjsRefuses501(`a contact card to ${CHANNEL_OR_BROADCAST}`) })
- @ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
+ @ApiResponse({ status: 503, description: SEND_503 })
async sendContact(@Param('sessionId') sessionId: string, @Body() dto: SendContactDto): Promise<MessageResponseDto> {
return this.messageService.sendContact(sessionId, dto);
}
@@ -427,7 +427,7 @@ export class MessageController {
description: `${CHANNEL_MEDIA_501} ${wwebjsRefuses501('a sticker to a status or broadcast list (`@broadcast`) either')}`,
})
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
- @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${RECIPIENT_LOOKUP_503}` })
+ @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${SEND_503}` })
async sendSticker(
@Param('sessionId') sessionId: string,
@Body() dto: SendMediaMessageDto,
@@ -456,7 +456,7 @@ export class MessageController {
'a poll to a status or broadcast list (`@broadcast`), nor one with `quotedMessageId` to a channel (`<id>@newsletter`)',
),
})
- @ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
+ @ApiResponse({ status: 503, description: SEND_503 })
async sendPoll(@Param('sessionId') sessionId: string, @Body() dto: SendPollDto): Promise<MessageResponseDto> {
return this.messageService.sendPoll(sessionId, dto);
}
@@ -477,7 +477,7 @@ export class MessageController {
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
@ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 501, description: wwebjsRefuses501(`a reply to ${CHANNEL_OR_BROADCAST}`) })
- @ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
+ @ApiResponse({ status: 503, description: SEND_503 })
async reply(@Param('sessionId') sessionId: string, @Body() dto: ReplyMessageDto): Promise<MessageResponseDto> {
return this.messageService.reply(sessionId, dto);
}
@@ -509,7 +509,7 @@ export class MessageController {
@ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 501, description: ENGINE_NOT_SUPPORTED_501 })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
- @ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
+ @ApiResponse({ status: 503, description: SEND_503 })
async clickButton(@Param('sessionId') sessionId: string, @Body() dto: ClickButtonDto): Promise<MessageResponseDto> {
return this.messageService.clickButton(sessionId, dto);
}
@@ -528,7 +528,7 @@ export class MessageController {
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
@ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
- @ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
+ @ApiResponse({ status: 503, description: SEND_503 })
async forward(@Param('sessionId') sessionId: string, @Body() dto: ForwardMessageDto): Promise<MessageResponseDto> {
return this.messageService.forward(sessionId, dto);
}
@@ -555,7 +555,7 @@ export class MessageController {
@ApiResponse({
status: 503,
description:
- RECIPIENT_LOOKUP_503 +
+ SEND_503 +
' ' +
'The whatsapp-web.js page connection died mid-request. The change may or may not have been applied; ' +
'repeating the request is safe, since it converges on the same state.',
@@ -789,7 +789,7 @@ export class MessageController {
@ApiResponse({
status: 503,
description:
- RECIPIENT_LOOKUP_503 +
+ SEND_503 +
' ' +
'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
'the gateway stopped waiting for a confirmation that never came.',
@@ -854,7 +854,7 @@ export class MessageController {
@ApiResponse({
status: 503,
description:
- RECIPIENT_LOOKUP_503 +
+ SEND_503 +
' ' +
'The whatsapp-web.js page connection died mid-request. The pin may or may not have been applied; a ' +
'retry is safe, but it restarts the pin duration from the moment it succeeds.',
@@ -882,7 +882,7 @@ export class MessageController {
@ApiResponse({
status: 503,
description:
- RECIPIENT_LOOKUP_503 +
+ SEND_503 +
' ' +
'The whatsapp-web.js page connection died mid-request. The change may or may not have been applied; ' +
'repeating the request is safe, since it converges on the same state.',
@@ -949,7 +949,7 @@ export class MessageController {
@ApiResponse({
status: 503,
description:
- RECIPIENT_LOOKUP_503 +
+ SEND_503 +
' ' +
'The whatsapp-web.js page connection died mid-request. The change may or may not have been applied; ' +
'repeating the request is safe, since it converges on the same state.',
diff --git a/src/modules/status/status.controller.ts b/src/modules/status/status.controller.ts
index 0f8e40031..0a2ddbfa0 100644
--- a/src/modules/status/status.controller.ts
+++ b/src/modules/status/status.controller.ts
@@ -12,6 +12,7 @@ import {
MEDIA_TOO_LARGE_413,
MEDIA_URL_PROXY_503,
SESSION_NOT_STARTED_404,
+ STATUS_POST_503,
} from '../../common/openapi/engine-status-responses';
@ApiTags('status')
@@ -80,6 +81,7 @@ export class StatusController {
type: StatusResultDto,
})
@ApiResponse({ status: 400, description: 'Invalid request, or the post was blocked by a plugin.' })
+ @ApiResponse({ status: 503, description: STATUS_POST_503 })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 404, description: SESSION_NOT_STARTED_404 })
async sendTextStatus(@Param('sessionId') sessionId: string, @Body() dto: SendTextStatusDto) {
@@ -107,7 +109,7 @@ export class StatusController {
'post was blocked by a plugin.',
})
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
- @ApiResponse({ status: 503, description: MEDIA_URL_PROXY_503 })
+ @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${STATUS_POST_503}` })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 404, description: SESSION_NOT_STARTED_404 })
async sendImageStatus(@Param('sessionId') sessionId: string, @Body() dto: SendImageStatusDto) {
@@ -134,7 +136,7 @@ export class StatusController {
'post was blocked by a plugin.',
})
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
- @ApiResponse({ status: 503, description: MEDIA_URL_PROXY_503 })
+ @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${STATUS_POST_503}` })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 404, description: SESSION_NOT_STARTED_404 })
async sendVideoStatus(@Param('sessionId') sessionId: string, @Body() dto: SendVideoStatusDto) {
@@ -162,7 +164,7 @@ export class StatusController {
'post was blocked by a plugin.',
})
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
- @ApiResponse({ status: 503, description: MEDIA_URL_PROXY_503 })
+ @ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${STATUS_POST_503}` })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 404, description: SESSION_NOT_STARTED_404 })
async sendVoiceStatus(@Param('sessionId') sessionId: string, @Body() dto: SendVoiceStatusDto) {
@@ -193,7 +195,9 @@ export class StatusController {
description:
'The whatsapp-web.js page connection died mid-request, so the revoke did not complete. Safe ' +
'to retry: revoking an already-revoked status converges. The status POST routes deliberately ' +
- 'do NOT answer this, because a replayed post would publish the status a second time.',
+ 'do NOT answer this for whatsapp-web.js, because a replayed post would publish the status a second ' +
+ 'time. On Baileys, also when WhatsApp rate-limits the revoke (code 429) or times out a query it ' +
+ 'awaits (code 408).',
})
async deleteStatus(@Param('sessionId') sessionId: string, @Param('id') statusId: string) {
await this.statusService.deleteStatus(sessionId, statusId);