Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(api): document 400/413 for a media url that cannot be fetched
Yudhi Armyndharis4f6152267267
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 414753c9e..e1225e00d 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -101,7 +101,7 @@ Validation failures (`statusCode: 400`) return `message` as an **array** of fiel| `403` | Forbidden | A valid, in-scope key whose **role** is below the route's `@RequireRole` requirement || `404` | Not Found | The addressed resource (session, message, webhook, batch, …) does not exist || `409` | Conflict | A uniqueness constraint was violated (e.g. duplicate name); a credential teardown for the same session name is still in flight on `start`/`delete` (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`); or, on routes that reach a WhatsApp engine, the engine exists but is not ready yet (retryable; each route section carries the exact wording); or, on a multi-node deployment, another node currently owns the session's live engine (retryable) |-| `413` | Payload Too Large | Base64 media exceeds the media byte cap (see §6.3) |+| `413` | Payload Too Large | Base64 or downloaded media exceeds the media byte cap (see §6.3) || `415` | Unsupported Media | The request has a body carrying a `Content-Encoding` other than `identity`; compressed request bodies are not accepted, as the aggregate body cap counts wire bytes || `429` | Too Many Requests | A rate limit was exceeded: the per-client-IP tiers, the ingress per-instance limit, or send pacing (body carries `code: 'SEND_PACING_LIMITED'` and `retryAfterSeconds`); honor `Retry-After` when present || `500` | Internal Server Error | Send failed at the WhatsApp engine or an unexpected server error |@@ -123,15 +123,15 @@ OpenWA uses **two** timestamp representations — be careful which a field is:All media send routes (`send-image`, `send-video`, `send-audio`, `send-document`, `send-sticker`) share one **flat** request DTO — `SendMediaMessageDto`. There is **no** nested `{ image: { url } }` wrapper; the media source fields sit at the top level of the body:-| Field | Type | Required | Constraints | Description |-| ---------- | -------- | ----------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |-| `chatId` | string | yes | non-empty | Recipient — `<phone>@c.us` or `<groupId>@g.us` |-| `url` | string | conditional | valid http/https URL; required when `base64` absent | Remote media URL. Fetched server-side through an SSRF guard; a blocked/internal URL yields `400` |-| `base64` | string | conditional | required when `url` absent | Raw base64 media data. Decoded size is checked against the media cap |-| `mimetype` | string | conditional | required when `base64` is used | MIME type, e.g. `image/jpeg`, `video/mp4`, `application/pdf` |-| `filename` | string | no | max 255 chars | Optional file name (also used as the persisted body fallback for documents) |-| `caption` | string | no | max 1024 chars | Optional caption (not persisted for audio) |-| `mentions` | string[] | no | array of WIDs | WIDs to @mention in the caption (e.g. `["[email protected]"]`). See **Mentions** below |+| Field | Type | Required | Constraints | Description |+| ---------- | -------- | ----------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `chatId` | string | yes | non-empty | Recipient — `<phone>@c.us` or `<groupId>@g.us` |+| `url` | string | conditional | valid http/https URL; required when `base64` absent | Remote media URL. Fetched server-side through an SSRF guard; a blocked/internal URL, a non-2xx answer, a timeout or a failed connection yields `400`, a download over the media cap `413` |+| `base64` | string | conditional | required when `url` absent | Raw base64 media data. Decoded size is checked against the media cap |+| `mimetype` | string | conditional | required when `base64` is used | MIME type, e.g. `image/jpeg`, `video/mp4`, `application/pdf` |+| `filename` | string | no | max 255 chars | Optional file name (also used as the persisted body fallback for documents) |+| `caption` | string | no | max 1024 chars | Optional caption (not persisted for audio) |+| `mentions` | string[] | no | array of WIDs | WIDs to @mention in the caption (e.g. `["[email protected]"]`). See **Mentions** below |Provide **exactly one** of `url` or `base64`. Omitting both, or supplying `base64` without `mimetype`, returns `400`.@@ -1751,15 +1751,15 @@ Send an image (by URL or base64) with an optional caption.**Request body** — `SendMediaMessageDto`-| Field | Type | Required | Constraints | Description |-| --------------- | ------ | ----------- | ------------------------------------- | --------------------------------------------------------------------------------- |-| chatId | string | Yes | non-empty | Target chat |-| url | string | Conditional | URL; required when `base64` is absent | http/https media URL (SSRF-guarded; a blocked internal URL maps to `400`) |-| base64 | string | Conditional | string; required when `url` is absent | Base64 media data (capped to the media byte limit) |-| mimetype | string | Conditional | string; required when using `base64` | MIME type of the media |-| filename | string | No | max 255 | File name |-| caption | string | No | max 1024 | Caption text |-| quotedMessageId | string | No | non-empty | Quote an earlier message, making this a reply — see [Quoted sends](#quoted-sends) |+| Field | Type | Required | Constraints | Description |+| --------------- | ------ | ----------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |+| chatId | string | Yes | non-empty | Target chat |+| url | string | Conditional | URL; required when `base64` is absent | http/https media URL (SSRF-guarded; a blocked internal or unreachable URL maps to `400`) |+| base64 | string | Conditional | string; required when `url` is absent | Base64 media data (capped to the media byte limit) |+| mimetype | string | Conditional | string; required when using `base64` | MIME type of the media |+| filename | string | No | max 255 | File name |+| caption | string | No | max 1024 | Caption text |+| quotedMessageId | string | No | non-empty | Quote an earlier message, making this a reply — see [Quoted sends](#quoted-sends) |```json{ "chatId": "[email protected]", "url": "https://example.com/image.jpg", "caption": "Check out this image!" }@@ -1771,7 +1771,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, session not active, or unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `413` base64 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+**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 · `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#### POST /api/sessions/:sessionId/messages/send-video@@ -1797,7 +1797,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 / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `413` base64 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+**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 · `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#### POST /api/sessions/:sessionId/messages/send-audio@@ -1823,7 +1823,7 @@ Send an audio message (by URL or base64). Uses `SendAudioMessageDto`. A `caption{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }```-**Errors:** `400` media validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `413` base64 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+**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 · `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#### POST /api/sessions/:sessionId/messages/send-document@@ -1856,7 +1856,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; Baileys falls back to the literal `file`.-**Errors:** `400` media validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `413` base64 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+**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 · `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#### POST /api/sessions/:sessionId/messages/send-location@@ -1956,7 +1956,7 @@ Send a sticker (by URL or base64; typically webp). Reuses `SendMediaMessageDto`.{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }```-**Errors:** `400` media validation failure / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `413` base64 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+**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 · `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#### POST /api/sessions/:sessionId/messages/send-poll@@ -2728,7 +2728,7 @@ Set the group's picture. The account must be a group admin.**Response** `200` — `{ "success": true, "message": "Group picture updated" }`-**Errors:** `400` the id does not name a group, the session is not active, or neither `url` nor `base64` was supplied · `401` missing/invalid API key · `403` key lacks OPERATOR role, or the engine refused (admin rights required) · `404` no such group · `409` the session is not connected (engine exists but is not `ready`) · `413` base64 media over the media cap (see §6.3) · `503` WhatsApp did not answer within the request budget — the change may or may not have been applied+**Errors:** `400` the id does not name a group, the session is not active, neither `url` nor `base64` was supplied, or the `url` answers non-2xx, times out or cannot be reached · `401` missing/invalid API key · `403` key lacks OPERATOR role, or the engine refused (admin rights required) · `404` no such group · `409` the session is not connected (engine exists but is not `ready`) · `413` base64 or downloaded media over the media cap (see §6.3) · `503` WhatsApp did not answer within the request budget — the change may or may not have been applied#### DELETE /api/sessions/:sessionId/groups/:groupId/picture@@ -4307,7 +4307,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) · `401` missing/invalid API key · `403` key lacks `OPERATOR` role · `404` session not found / not connected · `409` conflict or engine not ready (retryable) · `413` payload too large+**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 · `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)#### POST /api/sessions/:sessionId/status/send-video@@ -4356,7 +4356,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) · `401` missing/invalid API key · `403` key lacks `OPERATOR` role · `404` session not found / not connected · `409` conflict or engine not ready (retryable) · `413` payload too large+**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 · `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)#### POST /api/sessions/:sessionId/status/send-voice@@ -4393,7 +4393,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, or neither `url` nor `base64` supplied · `401` missing/invalid API key · `403` key lacks `OPERATOR` role · `404` session not found / not connected · `413` base64 media exceeds `MEDIA_DOWNLOAD_MAX_BYTES` · `409` conflict or engine not ready (retryable)+**Errors:** `400` validation failure, neither `url` nor `base64` supplied, or a `url` that answers non-2xx, times out or cannot be reached · `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)#### DELETE /api/sessions/:sessionId/status/:id@@ -6367,7 +6367,7 @@ or**Response** `200` — `{ "success": true, "message": "Profile picture updated" }`-**Errors:** `400` neither `url` nor `base64` provided / base64 without `mimetype` · `401` · `403` the whatsapp-web.js engine refused the change (the Baileys engine has no acceptance signal and answers `200`) · `409` conflict or engine not ready (retryable) · `413` payload too large · `503` session not ready or dependency unavailable (retryable)+**Errors:** `400` neither `url` nor `base64` provided / base64 without `mimetype` / a `url` that answers non-2xx, times out or cannot be reached · `401` · `403` the whatsapp-web.js engine refused the change (the Baileys engine has no acceptance signal and answers `200`) · `409` conflict or engine not ready (retryable) · `413` base64 or downloaded image over the media cap (see §6.3) · `503` session not ready or dependency unavailable (retryable)#### DELETE /api/sessions/:sessionId/profile/picture@@ -6499,7 +6499,7 @@ identified from the bytes.{ "base64": "T2dnUwACAAAA...", "mimetype": "audio/ogg; codecs=opus", "bytes": 14970 }```-**Errors:** `400` neither field given, or ffmpeg refused the input (its reason is included) · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role · `413` media above the size cap · `503` conversion is disabled, the ffmpeg binary is not runnable, or the conversion queue is saturated+**Errors:** `400` neither field given, a `url` that answers non-2xx, times out or cannot be reached, or ffmpeg refused the input (its reason is included) · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role · `413` media above the size cap · `503` conversion is disabled, the ffmpeg binary is not runnable, or the conversion queue is saturated#### POST /api/sessions/:sessionId/media/convert/video@@ -6507,7 +6507,7 @@ Convert video into an MP4 every WhatsApp client accepts: baseline H.264 with AACbounded at 1280 (never upscaled), index moved to the front so playback can start before the wholefile arrives.-**Errors:** `400` neither field given, or ffmpeg refused the input (its reason is included) · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role · `413` media above the size cap · `503` conversion is disabled, the ffmpeg binary is not runnable, or the conversion queue is saturated+**Errors:** `400` neither field given, a `url` that answers non-2xx, times out or cannot be reached, or ffmpeg refused the input (its reason is included) · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role · `413` media above the size cap · `503` conversion is disabled, the ffmpeg binary is not runnable, or the conversion queue is saturated**Response** `200`diff --git a/openapi.json b/openapi.jsonindex 8a2c759e6..17f850d8b 100644--- a/openapi.json+++ b/openapi.json@@ -2521,13 +2521,13 @@}},"400": {- "description": "Session not active or invalid request"+ "description": "Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached"},"409": {"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly."},"413": {- "description": "The decoded base64 media exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."+ "description": "The decoded base64 media, or the media downloaded from `url`, exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."},"501": {"description": "Sending media to a channel (`<id>@newsletter`) is not supported by the whatsapp-web.js engine — the page method it needs was removed by a WhatsApp Web update. Text to a channel still works."@@ -2584,13 +2584,13 @@}},"400": {- "description": "Session not active or invalid request"+ "description": "Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached"},"409": {"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly."},"413": {- "description": "The decoded base64 media exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."+ "description": "The decoded base64 media, or the media downloaded from `url`, exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."},"501": {"description": "Sending media to a channel (`<id>@newsletter`) is not supported by the whatsapp-web.js engine — the page method it needs was removed by a WhatsApp Web update. Text to a channel still works."@@ -2648,13 +2648,13 @@}},"400": {- "description": "Session not active or invalid request"+ "description": "Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached"},"409": {"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly."},"413": {- "description": "The decoded base64 media exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."+ "description": "The decoded base64 media, or the media downloaded from `url`, exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."},"501": {"description": "Sending media to a channel (`<id>@newsletter`) is not supported by the whatsapp-web.js engine — the page method it needs was removed by a WhatsApp Web update. Text to a channel still works."@@ -2712,13 +2712,13 @@}},"400": {- "description": "Session not active or invalid request"+ "description": "Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached"},"409": {"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly."},"413": {- "description": "The decoded base64 media exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."+ "description": "The decoded base64 media, or the media downloaded from `url`, exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."},"501": {"description": "Sending media to a channel (`<id>@newsletter`) is not supported by the whatsapp-web.js engine — the page method it needs was removed by a WhatsApp Web update. Text to a channel still works."@@ -2898,7 +2898,7 @@"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly."},"413": {- "description": "The decoded base64 media exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."+ "description": "The decoded base64 media, or the media downloaded from `url`, exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."},"501": {"description": "Sending media to a channel (`<id>@newsletter`) is not supported by the whatsapp-web.js engine — the page method it needs was removed by a WhatsApp Web update. Text to a channel still works."@@ -3757,7 +3757,7 @@"description": "Session not active or invalid request"},"413": {- "description": "The decoded base64 media exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."+ "description": "An item's decoded base64 media exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A `url` item is fetched after the `202`; one over the cap fails that item in the batch results (`GET /messages/batch/{batchId}`) instead. The whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default)."}},"summary": "Send messages to multiple recipients (async batch processing)",@@ -6028,7 +6028,7 @@}},"400": {- "description": "The id does not name a group, or the session is not active, or neither url nor base64 was supplied"+ "description": "The id does not name a group, the session is not active, neither url nor base64 was supplied, or the url answers non-2xx, times out or cannot be reached"},"403": {"description": "The engine refused the change — admin rights required"@@ -6040,7 +6040,7 @@"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly."},"413": {- "description": "The decoded base64 media exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."+ "description": "The decoded base64 media, or the media downloaded from `url`, exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."},"503": {"description": "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."@@ -6353,7 +6353,7 @@}},"400": {- "description": "Neither url nor base64 provided, base64 without mimetype, or session is not started"+ "description": "Neither url nor base64 provided, base64 without mimetype, session is not started, or the url answers non-2xx, times out or cannot be reached"},"403": {"description": "The whatsapp-web.js engine refused the picture change. The Baileys engine has no acceptance signal and answers 200 for an upload WhatsApp declined."@@ -6362,7 +6362,7 @@"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly."},"413": {- "description": "Decoded base64 image exceeds the configured media cap"+ "description": "The decoded base64 media, or the media downloaded from `url`, exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."},"503": {"description": "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."@@ -7931,7 +7931,7 @@}},"400": {- "description": "Neither url nor base64 provided, or the post was blocked by a plugin."+ "description": "Neither url nor base64 provided, the url answers non-2xx, times out or cannot be reached, or the post was blocked by a plugin."},"404": {"description": "No session is running under that id — it was never started, was stopped, or does not exist. These routes report an unstarted session as `404`, where the message and group routes report it as `400`."@@ -7940,7 +7940,7 @@"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly."},"413": {- "description": "Base64 media exceeds MEDIA_DOWNLOAD_MAX_BYTES."+ "description": "The decoded base64 media, or the media downloaded from `url`, exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."}},"summary": "Post an image status",@@ -7984,7 +7984,7 @@}},"400": {- "description": "Neither url nor base64 provided, or the post was blocked by a plugin."+ "description": "Neither url nor base64 provided, the url answers non-2xx, times out or cannot be reached, or the post was blocked by a plugin."},"404": {"description": "No session is running under that id — it was never started, was stopped, or does not exist. These routes report an unstarted session as `404`, where the message and group routes report it as `400`."@@ -7993,7 +7993,7 @@"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly."},"413": {- "description": "Base64 media exceeds MEDIA_DOWNLOAD_MAX_BYTES."+ "description": "The decoded base64 media, or the media downloaded from `url`, exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."}},"summary": "Post a video status",@@ -8037,7 +8037,7 @@}},"400": {- "description": "Neither url nor base64 provided, or the post was blocked by a plugin."+ "description": "Neither url nor base64 provided, the url answers non-2xx, times out or cannot be reached, or the post was blocked by a plugin."},"404": {"description": "No session is running under that id — it was never started, was stopped, or does not exist. These routes report an unstarted session as `404`, where the message and group routes report it as `400`."@@ -8046,7 +8046,7 @@"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly."},"413": {- "description": "Base64 media exceeds MEDIA_DOWNLOAD_MAX_BYTES."+ "description": "The decoded base64 media, or the media downloaded from `url`, exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs."}},"summary": "Post an audio status as a voice note",@@ -8123,7 +8123,7 @@}},"400": {- "description": "Neither url nor base64 given, or ffmpeg refused the input."+ "description": "Neither url nor base64 given, the url answers non-2xx, times out or cannot be reached, or ffmpeg refused the input."},"413": {"description": "The supplied media is above the media size cap."@@ -8174,7 +8174,7 @@}},"400": {- "description": "Neither url nor base64 given, or ffmpeg refused the input."+ "description": "Neither url nor base64 given, the url answers non-2xx, times out or cannot be reached, or ffmpeg refused the input."},"413": {"description": "The supplied media is above the media size cap."diff --git a/src/common/openapi/engine-status-responses.ts b/src/common/openapi/engine-status-responses.tsindex 23d077f12..c753a847e 100644--- a/src/common/openapi/engine-status-responses.ts+++ b/src/common/openapi/engine-status-responses.ts@@ -147,7 +147,17 @@ export const CHANNEL_MEDIA_501 =* came to expect a `400` the code never sends.*/export const MEDIA_TOO_LARGE_413 =- 'The decoded base64 media exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by ' +- 'default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and ' ++ 'The decoded base64 media, or the media downloaded from `url`, exceeds the media byte cap ' ++ '(`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by default). A whole request is separately bounded by `BODY_SIZE_LIMIT` (25 mb by default), and ' +'base64 inflates by about a third, so a large send usually meets that coarser limit first: the ' +'body parser rejects the request before this check runs.';++/**+ * send-bulk's 413: only the base64 of an item is checked while the request is open. A `url` item is+ * fetched after the 202, and one over the cap fails that item in the batch results instead.+ */+export const BULK_MEDIA_TOO_LARGE_413 =+ "An item's decoded base64 media exceeds the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`, 50 MiB by " ++ 'default). A `url` item is fetched after the `202`; one over the cap fails that item in the batch ' ++ 'results (`GET /messages/batch/{batchId}`) instead. The whole request is separately bounded by ' ++ '`BODY_SIZE_LIMIT` (25 mb by default).';diff --git a/src/modules/group/group.controller.ts b/src/modules/group/group.controller.tsindex 01c3a7c5a..8e84ce2b6 100644--- a/src/modules/group/group.controller.ts+++ b/src/modules/group/group.controller.ts@@ -477,7 +477,9 @@ export class GroupController {@ApiResponse({ status: 200, description: 'Group picture updated', type: GroupAckResponseDto })@ApiResponse({status: 400,- description: 'The id does not name a group, or the session is not active, or neither url nor base64 was supplied',+ description:+ 'The id does not name a group, the session is not active, neither url nor base64 was supplied, or ' ++ 'the url answers non-2xx, times out or cannot be reached',})@ApiResponse({ status: 403, description: 'The engine refused the change — admin rights required' })@ApiResponse({diff --git a/src/modules/media/media.controller.ts b/src/modules/media/media.controller.tsindex 719900ea7..6fe91e731 100644--- a/src/modules/media/media.controller.ts+++ b/src/modules/media/media.controller.ts@@ -50,7 +50,12 @@ export class MediaController {'mic bubble for Ogg/Opus; other formats arrive as an audio file that will not play.',type: ConvertedMediaResponseDto,})- @ApiResponse({ status: 400, description: 'Neither url nor base64 given, or ffmpeg refused the input.' })+ @ApiResponse({+ status: 400,+ description:+ 'Neither url nor base64 given, the url answers non-2xx, times out or cannot be reached, or ffmpeg ' ++ 'refused the input.',+ })@ApiResponse({ status: 413, description: 'The supplied media is above the media size cap.' })@ApiResponse({status: 503,@@ -72,7 +77,12 @@ export class MediaController {'front so the recipient can start playing before the whole file arrives.',type: ConvertedMediaResponseDto,})- @ApiResponse({ status: 400, description: 'Neither url nor base64 given, or ffmpeg refused the input.' })+ @ApiResponse({+ status: 400,+ description:+ 'Neither url nor base64 given, the url answers non-2xx, times out or cannot be reached, or ffmpeg ' ++ 'refused the input.',+ })@ApiResponse({ status: 413, description: 'The supplied media is above the media size cap.' })@ApiResponse({status: 503,diff --git a/src/modules/message/message.controller.ts b/src/modules/message/message.controller.tsindex 75c2cc18c..e48662287 100644--- a/src/modules/message/message.controller.ts+++ b/src/modules/message/message.controller.ts@@ -54,6 +54,7 @@ import {ENGINE_NOT_READY_409,ENGINE_NOT_SUPPORTED_501,MEDIA_TOO_LARGE_413,+ BULK_MEDIA_TOO_LARGE_413,MESSAGE_NOT_FOUND_404,RECIPIENT_UNREACHABLE_400,} from '../../common/openapi/engine-status-responses';@@ -189,7 +190,7 @@ export class MessageController {})@ApiResponse({status: 400,- description: 'Session not active or invalid request',+ description: 'Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached',})@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })@ApiResponse({ status: 501, description: CHANNEL_MEDIA_501 })@@ -213,7 +214,7 @@ export class MessageController {})@ApiResponse({status: 400,- description: 'Session not active or invalid request',+ description: 'Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached',})@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })@ApiResponse({ status: 501, description: CHANNEL_MEDIA_501 })@@ -237,7 +238,7 @@ export class MessageController {})@ApiResponse({status: 400,- description: 'Session not active or invalid request',+ description: 'Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached',})@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })@ApiResponse({ status: 501, description: CHANNEL_MEDIA_501 })@@ -261,7 +262,7 @@ export class MessageController {})@ApiResponse({status: 400,- description: 'Session not active or invalid request',+ description: 'Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached',})@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })@ApiResponse({ status: 501, description: CHANNEL_MEDIA_501 })@@ -750,7 +751,7 @@ export class MessageController {status: 400,description: 'Session not active or invalid request',})- @ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })+ @ApiResponse({ status: 413, description: BULK_MEDIA_TOO_LARGE_413 })async sendBulk(@Param('sessionId') sessionId: string,@Body() dto: SendBulkMessageDto,diff --git a/src/modules/profile/profile.controller.ts b/src/modules/profile/profile.controller.tsindex 0eded215f..7097d9ee1 100644--- a/src/modules/profile/profile.controller.ts+++ b/src/modules/profile/profile.controller.ts@@ -5,7 +5,7 @@ import { ProfileService } from './profile.service';import { SetProfileNameDto, SetProfileStatusDto, SetProfilePictureDto } from './dto/profile.dto';import { RequireRole } from '../auth/decorators/auth.decorators';import { ApiKeyRole } from '../auth/entities/api-key.entity';-import { ENGINE_NOT_READY_409 } from '../../common/openapi/engine-status-responses';+import { ENGINE_NOT_READY_409, MEDIA_TOO_LARGE_413 } from '../../common/openapi/engine-status-responses';@ApiTags('profile')@Controller('sessions/:sessionId/profile')@@ -64,7 +64,9 @@ export class ProfileController {@ApiResponse({ status: 200, description: 'Profile picture updated', type: ProfileAckResponseDto })@ApiResponse({status: 400,- description: 'Neither url nor base64 provided, base64 without mimetype, or session is not started',+ description:+ 'Neither url nor base64 provided, base64 without mimetype, session is not started, or the url ' ++ 'answers non-2xx, times out or cannot be reached',})@ApiResponse({status: 403,@@ -72,7 +74,7 @@ export class ProfileController {'The whatsapp-web.js engine refused the picture change. The Baileys engine has no acceptance ' +'signal and answers 200 for an upload WhatsApp declined.',})- @ApiResponse({ status: 413, description: 'Decoded base64 image exceeds the configured media cap' })+ @ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })@ApiResponse({status: 503,description:diff --git a/src/modules/status/status.controller.ts b/src/modules/status/status.controller.tsindex 67eef034c..0f10a8715 100644--- a/src/modules/status/status.controller.ts+++ b/src/modules/status/status.controller.ts@@ -7,7 +7,11 @@ import { SendTextStatusDto } from './dto/send-text-status.dto';import { SendImageStatusDto, SendVideoStatusDto, SendVoiceStatusDto } from './dto/send-media-status.dto';import { RequireRole } from '../auth/decorators/auth.decorators';import { ApiKeyRole } from '../auth/entities/api-key.entity';-import { ENGINE_NOT_READY_409, SESSION_NOT_STARTED_404 } from '../../common/openapi/engine-status-responses';+import {+ ENGINE_NOT_READY_409,+ MEDIA_TOO_LARGE_413,+ SESSION_NOT_STARTED_404,+} from '../../common/openapi/engine-status-responses';@ApiTags('status')@Controller('sessions/:sessionId/status')@@ -97,9 +101,11 @@ export class StatusController {})@ApiResponse({status: 400,- description: 'Neither url nor base64 provided, or the post was blocked by a plugin.',+ description:+ 'Neither url nor base64 provided, the url answers non-2xx, times out or cannot be reached, or the ' ++ 'post was blocked by a plugin.',})- @ApiResponse({ status: 413, description: 'Base64 media exceeds MEDIA_DOWNLOAD_MAX_BYTES.' })+ @ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })@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) {@@ -121,9 +127,11 @@ export class StatusController {})@ApiResponse({status: 400,- description: 'Neither url nor base64 provided, or the post was blocked by a plugin.',+ description:+ 'Neither url nor base64 provided, the url answers non-2xx, times out or cannot be reached, or the ' ++ 'post was blocked by a plugin.',})- @ApiResponse({ status: 413, description: 'Base64 media exceeds MEDIA_DOWNLOAD_MAX_BYTES.' })+ @ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })@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) {@@ -146,9 +154,11 @@ export class StatusController {})@ApiResponse({status: 400,- description: 'Neither url nor base64 provided, or the post was blocked by a plugin.',+ description:+ 'Neither url nor base64 provided, the url answers non-2xx, times out or cannot be reached, or the ' ++ 'post was blocked by a plugin.',})- @ApiResponse({ status: 413, description: 'Base64 media exceeds MEDIA_DOWNLOAD_MAX_BYTES.' })+ @ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })@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) {