Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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 AAC
bounded at 1280 (never upscaled), index moved to the front so playback can start before the whole
file 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.json
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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) {