Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

13.8 KB
Raw Blame
/**
 * Response descriptions shared by every route that reaches a WhatsApp engine.
 *
 * Kept in one place rather than repeated per controller: the text describes the engine's own
 * behaviour, not any one route's, so eleven copies would drift apart the moment one of them was
 * reworded — which is how the contract fell behind the code in the first place.
 */

/**
 * `EngineNotReadyError` (409) — thrown by every adapter's `ensureReady()` guard, which each engine
 * method calls before touching the socket or the page. The guard fires when an engine EXISTS but is
 * not `READY`; a session with no engine at all never reaches it, because the service resolves the
 * engine first and throws `400 Session is not started`. Distinct too from the 409 the session, auth
 * and plugin routes declare, which reports a semantic conflict — a name already taken, a plugin
 * already installed, a session already running.
 */
export const ENGINE_NOT_READY_409 =
  '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.';

/**
 * `EngineRegistry.require()`'s default `BadRequestException` (400): the session has no engine at all,
 * the case ENGINE_NOT_READY_409 leaves out. The catalog and status routes answer this with a 404
 * instead; see SESSION_NOT_STARTED_404.
 */
export const SESSION_NOT_STARTED_400 =
  'The session is not started: no engine is running for it (never started, stopped, or logged out). ' +
  'Start the session and retry.';

/**
 * `EngineNotReadyError` (409) on `POST /sessions/:sessionId/pairing-code`, where the generic wording
 * above points the caller at the wrong state: both engines accept a pairing request only while the
 * session is `qr_ready`, and a session that reads `ready` is already linked and answers `400`.
 *
 * `qr_ready` is necessary but not sufficient on Baileys, hence the closing-socket sentence: the guard
 * also tests `ws.isOpen`, and the status trails the transport because Baileys emits its close only
 * after `await ws.close()` resolves. Same shape as the reload window ENGINE_NOT_READY_409 names, and
 * for the same reason: a caller that treats the documented status as sufficient would otherwise read
 * a legitimate retryable 409 as a bad state.
 */
export const PAIRING_NOT_READY_409 =
  'The session is not waiting to be linked: the engine is still connecting, or reconnecting after a ' +
  'drop, so the request never reached WhatsApp. Wait for `status` to read `qr_ready` and retry. Once a ' +
  'code has been accepted the session moves through `authenticating` and `initializing` to `ready` and ' +
  'answers this until then; wait for `ready` in that case. A session that reads `ready` is already ' +
  'linked and answers `400` instead. One window answers this while the session still reads ' +
  '`qr_ready`: on the Baileys engine a socket that has begun closing stops accepting a pairing ' +
  'request before the status catches up, which on a silently dropped connection takes until the ' +
  "WebSocket's close timeout (30 s); retry, and the status follows shortly.";

/**
 * `EngineTransportError` (503) on `POST /sessions/:sessionId/pairing-code`, where the whatsapp-web.js
 * engine bounds each attempt and retries the navigation shapes: WhatsApp Web reloads its QR page every
 * few seconds while unpaired, so a request can land mid-navigation. Only an exhausted budget is
 * reported here, and an attempt can exhaust it on a bare timeout with no navigation behind it, so the
 * description says what the gateway knows rather than naming a cause. A refusal WhatsApp itself sends
 * is not navigation-shaped and propagates on the first attempt instead.
 */
export const PAIRING_TRANSPORT_503 =
  'The pairing code could not be generated: the gateway stopped waiting after its attempt budget, ' +
  'usually because WhatsApp Web kept reloading its QR page. The condition is transient and the ' +
  "request is worth retrying; the last attempt's reason is carried in the message. An attempt that " +
  'timed out may still have reached WhatsApp, and a retry starts the linking flow again, with the ' +
  'same risk of unlinking an already-linked device that this route carries generally. The Baileys ' +
  'engine does not answer this, having no page to reload.';

/**
 * The catalog and status services pass a `NotFoundException` factory to `EngineRegistry.require()`
 * instead of taking its `BadRequestException` default, so on those routes an unstarted session is a
 * 404 rather than the 400 every other engine module answers. Documented rather than changed: the
 * status code is the contract those routes already have.
 */
export const SESSION_NOT_STARTED_404 =
  '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`.';

/**
 * `RecipientUnreachableError` (400) — whatsapp-web.js could not resolve the recipient to an
 * addressable id, so the send never left the gateway. The wording stays non-exclusive: 400 is also
 * what body validation and an inactive session answer on these routes, and the earlier text claimed
 * a 404 meaning that four of the six routes carrying this constant do not even declare.
 */
export const RECIPIENT_UNREACHABLE_400 =
  'Baileys rejects a phone number reported as unregistered. ' +
  'The request was rejected before anything was sent. Among the causes: the recipient could not be ' +
  'addressed — WhatsApp reports no deliverable id for that `chatId`, which is how it says the number ' +
  'is not on WhatsApp — as well as body validation and a session that is not active.';

/** `EngineRefusedError` (403) — the request was well formed; WhatsApp itself refused it. */
export const ENGINE_REFUSED_403 =
  'WhatsApp refused the operation. The request was well formed — the refusal happened WhatsApp-side, ' +
  'most often because the account lacks the admin rights the operation requires.';

export const RECIPIENT_LOOKUP_503 =
  'Baileys could not complete the recipient lookup within the request budget. On send routes, ' +
  'no message was handed to WhatsApp for this lookup failure.';

/**
 * `EngineThrottledError` (429) and `EngineTransportError` (408), both 503, from `mapSendRefusal`: on Baileys a
 * send, reaction, delete, pin, edit or status post awaits several queries before it relays the message, and
 * WhatsApp turns a throttled or timed out one away with that code. They differ in what they prove: a throttle
 * sent nothing, so the idempotency key is freed; a timeout proves nothing, so the key stays taken.
 */
const SEND_REFUSAL_503 =
  'On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees ' +
  'its `Idempotency-Key`) or times out a query it awaits (code 408: the outcome is not proven, and a keyed ' +
  'send keeps its `Idempotency-Key` taken).';

/**
 * Both texts, for every route that reaches the Baileys send path. `presence/subscribe` shares the recipient
 * lookup but sends nothing, so it keeps RECIPIENT_LOOKUP_503 alone.
 */
export const SEND_503 = `${RECIPIENT_LOOKUP_503} ${SEND_REFUSAL_503}`;

/**
 * The same two refusals on a Baileys status post. It has no recipient to look up and takes no idempotency key,
 * so the text names the post only.
 */
export const STATUS_POST_503 =
  'On Baileys, WhatsApp can answer the post with a 503: it rate-limited the request (code 429: nothing was ' +
  'posted) or timed out a query the post awaits (code 408: the outcome is not proven, so the post may have ' +
  'been published).';

/** `MessageNotFoundError` (404): outside the adapter's lookup window, or revoked. */
export const MESSAGE_NOT_FOUND_404 =
  "No such message: the id is outside the engine's lookup window (roughly the last hundred messages " +
  'of the chat, or absent from the Baileys store) or the message was revoked.';

/**
 * `MessageNotFoundError` (404) on the send routes that take a `quotedMessageId`. Not the react/delete
 * wording: whatsapp-web.js looks the quote up by id in the page's message collection and then by
 * `Msg.getMessagesById`, with no window of recent messages, and does not refuse a quote that resolves
 * but cannot be replied to.
 */
export const QUOTED_MESSAGE_NOT_FOUND_404 =
  'The `quotedMessageId` could not be resolved: the whatsapp-web.js page does not hold it, or the ' +
  'Baileys store does not (it was never received or sent by this session, or it was evicted or deleted). ' +
  'On whatsapp-web.js a message that resolves but cannot be replied to is sent without the quote.';

/** `ChannelNotFoundError` (404), on routes addressed by channel id. */
export const CHANNEL_NOT_FOUND_404 =
  "No such channel — the id is not among the session's subscribed channels, either because it is " +
  'wrong or because the channel has not synced into the local collection yet.';

/**
 * `ChannelNotFoundError` (404) on `POST /channels/subscribe`, which takes an invite code and no
 * channel id at all — so the id-based wording above would describe the wrong thing.
 */
export const CHANNEL_INVITE_NOT_FOUND_404 =
  'The invite code does not resolve to a channel — it is wrong, expired, or revoked. This route takes ' +
  'an invite code rather than a channel id.';

/**
 * `EngineNotSupportedError` (501) on `POST /messages/send-text`, which is supported by both engines;
 * only the caller-supplied link preview is not. The generic engine-wide wording would overstate it.
 */
export const CUSTOM_LINK_PREVIEW_501 =
  'A caller-supplied `customLinkPreview` is not supported by the whatsapp-web.js engine — only ' +
  'Baileys can attach one. The send itself is supported on both; omit the field, or use `linkPreview`.';

/**
 * `GroupNotFoundError` (404) — the id names a group, but no such group is known.
 *
 * It does NOT cover an id that addresses a 1:1 chat: every route carrying this response guards the
 * id shape first and answers 400, so advertising the 1:1 case here would contradict the 400 on the
 * same route. Keep the two descriptions disjoint — a caller uses them to tell "wrong kind of id"
 * (fix the request) apart from "right kind, no such group" (the group is gone or was never joined).
 */
export const GROUP_NOT_FOUND_404 = 'No such group — the id is unknown.';

/** `LabelNotFoundError` (404) — never created, or the account is not a Business one. */
export const LABEL_NOT_FOUND_404 =
  'No such label — it was never created, or the account is not a WhatsApp Business one and holds no ' +
  'labels at all. Both are the same answer to the caller.';

/** `EngineNotSupportedError` (501) — in the engine contract, but not implementable on this engine. */
export const ENGINE_NOT_SUPPORTED_501 =
  'The active engine cannot serve this operation. It is part of the engine contract, but the engine ' +
  'currently running has no implementation for it.';

/** `ChannelMediaNotSupportedError` (501) — media to an `@newsletter` recipient on whatsapp-web.js. */
export const CHANNEL_MEDIA_501 =
  '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.';

/**
 * `PayloadTooLargeException` (413), thrown by `assertBase64WithinMediaCap` when an outbound base64
 * payload's DECODED size exceeds the shared media byte cap, before the payload is persisted or handed
 * to an engine.
 *
 * Declared as a constant for the same reason as the rest of this file: the cap belongs to the media
 * path, not to any one route, and it already reaches nine call sites. It was answered by every media
 * send long before it was declared on any of them, which is how a caller reading only the contract
 * came to expect a `400` the code never sends.
 */
export const MEDIA_TOO_LARGE_413 =
  '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).';

/**
 * `ServiceUnavailableException` (503), thrown by `loadRemoteMediaBuffer` when a `url` fetched through
 * the session's egress proxy fails before any response arrives. undici cannot tell a dead proxy from
 * an unreachable target there, so the text names both rather than blaming either one.
 */
export const MEDIA_URL_PROXY_503 =
  'The session routes its `url` fetches through an egress proxy, and the fetch failed or timed out ' +
  'before any response arrived, so the request was not carried out. The proxy or the target behind it ' +
  'may be at fault; the gateway cannot tell which. Retryable, but a `503` that persists while the proxy ' +
  'works points at the `url`. Without a session proxy the same failure answers `400`.';