Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(contact): document the throttled profile-picture 503

Yudhi Armyndharis60310cd308a2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b39ea54c3..41dfca95a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -286,7 +286,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Baileys: link previews follow redirects, so bare-domain, `http://` and short links get one, and their titles and descriptions are no longer cut at an apostrophe or quote.
- Baileys: API sends no longer go out as disappearing messages after the chat turns them off, and follow a changed timer at once.
- Baileys: a contact's `profilePicUrl` is no longer the picture-change marker `changed` or `removed`; only a URL is reported.
-- Baileys: a profile-picture lookup whose connection drops answers `503` instead of `200` with a null `url`.
+- Baileys: a profile-picture lookup whose connection drops, or that WhatsApp rate-limits or times out (code 429 or 408), answers `503` instead of `200` with a null `url`.
- Baileys: a WhatsApp refusal on the catalog routes answers `403` instead of `500`, an account without a catalog gets the documented empty answer, and a refused product lookup in `send-product` no longer counts toward the send breaker.
- Baileys: a group, channel or catalog call that WhatsApp rate-limits or times out answers `503` instead of a `403` permissions error or a `500`, except a timed-out group or channel create, which may have succeeded and so answers `500` instead of a retryable `503`.
- Baileys: a call-link request WhatsApp never answers gets `503` instead of `500`; a retry can create a second link.
@@ -477,7 +477,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- A deployment with a unit suffix or fraction in an integer setting, `0` in a rate-limit window, a `BODY_SIZE_LIMIT` of `0` or with an unknown unit, a negative reaper or reconciler interval (set `0` to turn a sweep off), a retention or grace window above 36500 days, a timer value past Node's limit, or a boolean flag such as `ENABLE_SWAGGER` spelled other than `true` or `false` now fails to start; the boot error names the key.
- ⚠️ **Breaking (API).** Webhook filters and automation rule conditions with a key other than `conditions`, or a condition key other than `field`, `operator`, `value` and `caseSensitive`, are now refused with `400`, and `POST /api/infra/import-data` refuses a backup holding such a webhook or automation rule; remove the extra keys.
- ⚠️ **Breaking (API).** A group create or participant add naming more new contacts than a whole day's cold-reachout allowance gets `400` without `retryAfterSeconds` instead of `429`; split the batch.
-- ⚠️ **Breaking (API).** Media conversion answers `503` instead of `400` when ffmpeg cannot be started, and on Baileys a rate-limited or timed-out group, channel or catalog call answers `503` instead of `403`, except a group or channel create that WhatsApp times out (code 408), which may have succeeded and answers `500` instead of `403`; a profile-picture lookup whose connection drops answers `503` instead of `200` with a null `url`; a client that branched on the old code needs updating.
+- ⚠️ **Breaking (API).** Media conversion answers `503` instead of `400` when ffmpeg cannot be started, and on Baileys a rate-limited or timed-out group, channel or catalog call answers `503` instead of `403`, except a group or channel create that WhatsApp times out (code 408), which may have succeeded and answers `500` instead of `403`; a profile-picture lookup whose connection drops, or that WhatsApp rate-limits or times out (code 429 or 408), answers `503` instead of `200` with a null `url`; a client that branched on the old code needs updating.
- ⚠️ **Breaking (API).** `POST /api/sessions` refuses an out-of-range or mistyped `config.maxReconnectAttempts`, `config.reconnectBaseDelay` or `config.autoRejectCalls` with `400` instead of storing it; a string such as `"true"` or `"5"` is still accepted and stored typed.
- `PATCH /api/sessions/:sessionId/config` answers `409` when concurrent updates to the same session keep conflicting; retry it.
- ⚠️ **Breaking (API).** API key create and update refuse with `400` an `expiresAt` that is valid ISO 8601 but not a date the gateway can read, such as the week form `2026-W40-1`, and a key already stored with such an expiry is treated as expired; give it a new expiry with `PUT /api/auth/api-keys/:id`.
diff --git a/src/modules/contact/contact.controller.ts b/src/modules/contact/contact.controller.ts
index 332cd64c2..ed20c9f3c 100644
--- a/src/modules/contact/contact.controller.ts
+++ b/src/modules/contact/contact.controller.ts
@@ -176,7 +176,8 @@ export class ContactController {
status: 503,
description:
'WhatsApp did not answer the lookup. Deliberately not reported as `url: null` — that is the ' +
- 'same answer a contact with no picture gives, and a caller cannot tell them apart.',
+ 'same answer a contact with no picture gives, and a caller cannot tell them apart. On Baileys, also ' +
+ 'answered when WhatsApp rate-limits or times out the lookup (code 429 or 408); retry after a pause.',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
async getProfilePicture(@Param('sessionId') sessionId: string, @Param('contactId') contactId: string) {