Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): qualify the throttle 503 for multi-field group settings

Yudhi Armyndharis0a63dbe157ed
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 73dcd321a..6aa64a6c5 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -3381,6 +3381,12 @@ Update group settings. Each present field maps to one engine call; absent fields
> only field with a deterministic per-engine refusal (whatsapp-web.js always `501`s it); applying
> anything else first would leave a half-applied patch behind when that call throws. `memberAddMode`
> is supported on both engines and is therefore applied after it.
+>
+> The fields are applied one at a time. A failure on the first propagates unchanged, with nothing
+> applied; a failure on a later one leaves the earlier ones applied, keeps the failed call's status
+> (a `503` WhatsApp throttle or timeout included) and names both in its message:
+> `Group settings only partially applied: 'announce' failed (...); already applied: ephemeralSeconds`.
+> Re-read the settings before retrying, or send one field per request.
**Response** `200`
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index 92251586d..bc20c3c58 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -20,7 +20,7 @@ OpenWA ships five official, hand-written client libraries for the REST API. They
- **One client, fluent resources.** A single client object (`OpenWAClient` / `OpenWA\Client`) exposes every resource as a property — `client.messages.sendText(...)`, `client.sessions.start(...)`. All five SDKs expose the **same** resource surface; only the language idioms differ (camelCase methods + objects in JS/PHP/Java, snake_case methods + dicts in Python, exported fields + structs in Go).
- **It is a request/response client, not an event SDK.** There is no WebSocket, EventEmitter, or `client.on(...)`. To receive inbound messages and acks, register a webhook (the `webhooks` resource) and host your own receiver, checking `X-OpenWA-Signature` with the SDK helper (`verifyWebhookSignature` in JavaScript, `verify_webhook_signature` in Python, `VerifyWebhookSignature` in Go, `WebhookSignature.verify` in Java, `WebhookSignature::verify` in PHP), or connect to the real-time Socket.IO API directly (see [API Specification §6.5](./06-api-specification.md)).
-- **Typed errors.** Non-2xx responses raise/throw a typed error mapped from the HTTP status (`401/403/404/409/429/501/503`), plus a timeout error — all `instanceof`/`catch`-checkable. See each language's Error Handling subsection.
+- **Typed errors.** Non-2xx responses raise/throw a typed error mapped from the HTTP status (`401/403/404/409/429/501/503`), plus a timeout error — all `instanceof`/`catch`-checkable. See each language's Error Handling subsection. A Baileys throttle `503` on a send or a single write means nothing was sent or applied, but a group settings update with several fields applies them one at a time, so a `503` on a later field leaves the earlier ones applied and lists them after `already applied:` in its message: re-read the settings before retrying, or send one field per request.
- **Injectable transport.** The HTTP layer is replaceable (`fetch` in JS, an `httpx` transport in Python, a Guzzle client in PHP) — the extension point for retry/observability middleware and for testing without the network.
- **Safe by default.** Redirects are never followed (so the API key is never re-sent to a redirect target), the auth/JSON headers always take precedence over caller-supplied defaults, path segments are percent-encoded, a base-URL path prefix (e.g. behind a reverse proxy at `/v1`) is preserved, and there is a default 30s per-request timeout. **No automatic retries by default** — in JS, Python, PHP, and Java wrap calls in your own backoff if you need them (especially for `429`); the Go SDK additionally ships an opt-in `WithRetry(RetryPolicy)` that never replays a `POST` or `PATCH` after a network error and limits their retries to `429`/`503`.
diff --git a/sdk/go/README.md b/sdk/go/README.md
index b44102cf9..fa956363d 100644
--- a/sdk/go/README.md
+++ b/sdk/go/README.md
@@ -129,11 +129,15 @@ by default) after a run of send failures, otherwise up to the next UTC day.
`APIError.Header` holds the response headers. A timeout surfaces as
`*openwa.TimeoutError`. A 503 does not always prove a write was never carried
out: when WhatsApp timed out, the change may still have been applied, so re-read
-the state before repeating it. A throttle is the exception: it was turned away
-before it ran, so nothing was sent, and a keyed send frees its
-`Idempotency-Key`. In a routed deployment a forward that fails before reaching
-the owner node answers 503, one that fails after the request reached it answers
-502 or 504, and a 503 from the owner itself is relayed unchanged.
+the state before repeating it. A throttle on a send or a single write is the
+exception: it was turned away before it ran, so nothing was sent or applied, and
+a keyed send frees its `Idempotency-Key`. A group settings update with several
+fields applies them one at a time, so a 503 on a later field, a throttle
+included, leaves the earlier ones applied; its message lists them after
+`already applied:`, so re-read the settings before retrying, or send one field
+per request. In a routed deployment a forward that fails before reaching the
+owner node answers 503, one that fails after the request reached it answers 502
+or 504, and a 503 from the owner itself is relayed unchanged.
## Retries
diff --git a/sdk/go/errors.go b/sdk/go/errors.go
index b52f40bea..c365db43d 100644
--- a/sdk/go/errors.go
+++ b/sdk/go/errors.go
@@ -55,18 +55,22 @@ var (
// request straight away prolongs the throttle. A catalog 503 can persist
// because WhatsApp may never answer that query, so bound any retry.
//
- // A throttle turned the request away before it ran, so nothing was sent or
- // applied, and a keyed send frees its Idempotency-Key for the retry. A
- // timeout proves nothing: the write may still have been applied, and a
- // keyed send keeps its key taken. The non-idempotent sends are deliberately
- // left unbounded by the gateway so a slow WhatsApp reply never answers one,
- // and in a multi-node deployment a forward that fails before reaching the
- // owner node answers 503. A 503 from the owner itself is relayed unchanged
- // and keeps its meaning, so a bounded write that timed out may still have
- // been applied; re-read the state before repeating it. A forward that fails
- // after the request was sent answers 502 or 504 instead: the owner may
- // already have carried it out, so do not repeat a non-idempotent send on
- // those unchecked.
+ // On a send or a single write, a throttle turned the request away before it
+ // ran, so nothing was sent or applied, and a keyed send frees its
+ // Idempotency-Key for the retry. A group settings update with several
+ // fields applies them one at a time, so a 503 on a later field, a throttle
+ // included, leaves the earlier ones applied; the message lists them after
+ // "already applied:", so re-read the settings before retrying, or send one
+ // field per request. A timeout proves nothing: the write may still have
+ // been applied, and a keyed send keeps its key taken. The non-idempotent
+ // sends are deliberately left unbounded by the gateway so a slow WhatsApp
+ // reply never answers one, and in a multi-node deployment a forward that
+ // fails before reaching the owner node answers 503. A 503 from the owner
+ // itself is relayed unchanged and keeps its meaning, so a bounded write
+ // that timed out may still have been applied; re-read the state before
+ // repeating it. A forward that fails after the request was sent answers 502
+ // or 504 instead: the owner may already have carried it out, so do not
+ // repeat a non-idempotent send on those unchecked.
ErrServiceUnavailable = errors.New("openwa: service unavailable")
)
diff --git a/sdk/java/README.md b/sdk/java/README.md
index f9cf86a3e..afe8b4192 100644
--- a/sdk/java/README.md
+++ b/sdk/java/README.md
@@ -127,7 +127,7 @@ try {
| `OpenWAApiError` | — | Any other non-2xx (carries `.status()`) |
| `OpenWATimeoutError` | — | Request exceeded the configured timeout |
-All extend `OpenWAError` (a `RuntimeException`). 503 means the gateway could not complete the request right now: the path to WhatsApp failed, the gateway is draining or short of a dependency, or, on Baileys, WhatsApp throttled (code 429) or timed out (code 408) the request. Back off and retry later instead of at once, because repeating a throttled request straight away prolongs the throttle; a catalog 503 can persist because WhatsApp may never answer that query, so bound any retry. A 429 from the global rate limiter lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and `retryAfterSeconds()` carries its `Retry-After` header. A 429 whose `code()` is `"SEND_PACING_LIMITED"` is usually not transient: do not retry it before `retryAfterSeconds()`, which then comes from the body: a few seconds when only sends still in flight caused it, the rest of the failure breaker's cooldown (`SEND_PACING_BREAKER_COOLDOWN_MS`, 15 minutes by default) after a run of send failures, otherwise up to the next UTC day. `headers()` returns the response headers. A 503 does not always prove a write was never carried out: when WhatsApp timed out, the change may still have been applied, so re-read the state before repeating it. A throttle is the exception: it was turned away before it ran, so nothing was sent, and a keyed send frees its `Idempotency-Key`. In a routed deployment a forward that fails before reaching the owner node answers 503, one that fails after the request reached it answers 502 or 504, and a 503 from the owner itself is relayed unchanged.
+All extend `OpenWAError` (a `RuntimeException`). 503 means the gateway could not complete the request right now: the path to WhatsApp failed, the gateway is draining or short of a dependency, or, on Baileys, WhatsApp throttled (code 429) or timed out (code 408) the request. Back off and retry later instead of at once, because repeating a throttled request straight away prolongs the throttle; a catalog 503 can persist because WhatsApp may never answer that query, so bound any retry. A 429 from the global rate limiter lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and `retryAfterSeconds()` carries its `Retry-After` header. A 429 whose `code()` is `"SEND_PACING_LIMITED"` is usually not transient: do not retry it before `retryAfterSeconds()`, which then comes from the body: a few seconds when only sends still in flight caused it, the rest of the failure breaker's cooldown (`SEND_PACING_BREAKER_COOLDOWN_MS`, 15 minutes by default) after a run of send failures, otherwise up to the next UTC day. `headers()` returns the response headers. A 503 does not always prove a write was never carried out: when WhatsApp timed out, the change may still have been applied, so re-read the state before repeating it. A throttle on a send or a single write is the exception: it was turned away before it ran, so nothing was sent or applied, and a keyed send frees its `Idempotency-Key`. A group settings update with several fields applies them one at a time, so a 503 on a later field, a throttle included, leaves the earlier ones applied; its message lists them after `already applied:`, so re-read the settings before retrying, or send one field per request. In a routed deployment a forward that fails before reaching the owner node answers 503, one that fails after the request reached it answers 502 or 504, and a 503 from the owner itself is relayed unchanged.
## Receiving webhooks
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWAServiceUnavailableError.java b/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWAServiceUnavailableError.java
index d754080d7..cb70bd47c 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWAServiceUnavailableError.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWAServiceUnavailableError.java
@@ -13,16 +13,19 @@ import java.util.Map;
* throttled request straight away prolongs the throttle. A catalog 503 can persist because WhatsApp
* may never answer that query, so bound any retry.
*
- * <p>A throttle turned the request away before it ran, so nothing was sent or applied, and a keyed
- * send frees its {@code Idempotency-Key} for the retry. A timeout proves nothing: the write may
- * still have been applied, and a keyed send keeps its key taken. The non-idempotent sends are
- * deliberately left unbounded by the gateway so a slow WhatsApp reply never answers one, and in a
- * multi-node deployment a forward that fails before reaching the owner node answers 503. A 503 from
- * the owner itself is relayed unchanged and keeps its meaning, so a bounded write such as a group,
- * channel, contact or profile change that timed out may still have been applied; re-read the state
- * before repeating it. A forward that fails after the request was sent answers 502 or 504 instead
- * (a plain {@link OpenWAApiError}): the owner may already have carried it out, so do not repeat a
- * non-idempotent send on those unchecked.
+ * <p>On a send or a single write, a throttle turned the request away before it ran, so nothing was
+ * sent or applied, and a keyed send frees its {@code Idempotency-Key} for the retry. A group
+ * settings update with several fields applies them one at a time, so a 503 on a later field, a
+ * throttle included, leaves the earlier ones applied; the message lists them after
+ * {@code already applied:}, so re-read the settings before retrying, or send one field per request.
+ * A timeout proves nothing: the write may still have been applied, and a keyed send keeps its key
+ * taken. The non-idempotent sends are deliberately left unbounded by the gateway so a slow WhatsApp
+ * reply never answers one, and in a multi-node deployment a forward that fails before reaching the
+ * owner node answers 503. A 503 from the owner itself is relayed unchanged and keeps its meaning, so
+ * a bounded write such as a group, channel, contact or profile change that timed out may still have
+ * been applied; re-read the state before repeating it. A forward that fails after the request was
+ * sent answers 502 or 504 instead (a plain {@link OpenWAApiError}): the owner may already have
+ * carried it out, so do not repeat a non-idempotent send on those unchecked.
*/
public class OpenWAServiceUnavailableError extends OpenWAApiError {
public OpenWAServiceUnavailableError(String message, int status, Object body, String errorKind) {
diff --git a/sdk/javascript/README.md b/sdk/javascript/README.md
index d31d084ca..cd7aa6715 100644
--- a/sdk/javascript/README.md
+++ b/sdk/javascript/README.md
@@ -67,11 +67,15 @@ sends still in flight caused it, the rest of the failure breaker's cooldown
failures, otherwise up to the next UTC day. Every API error also exposes the
response `.headers`. A 503 does not always prove a write was never carried out:
when WhatsApp timed out, the change may still have been applied, so re-read the
-state before repeating it. A throttle is the exception: it was turned away
-before it ran, so nothing was sent, and a keyed send frees its
-`Idempotency-Key`. In a routed deployment a forward that fails before reaching
-the owner node answers 503, one that fails after the request reached it answers
-502 or 504, and a 503 from the owner itself is relayed unchanged.
+state before repeating it. A throttle on a send or a single write is the
+exception: it was turned away before it ran, so nothing was sent or applied, and
+a keyed send frees its `Idempotency-Key`. A group settings update with several
+fields applies them one at a time, so a 503 on a later field, a throttle
+included, leaves the earlier ones applied; its message lists them after
+`already applied:`, so re-read the settings before retrying, or send one field
+per request. In a routed deployment a forward that fails before reaching the
+owner node answers 503, one that fails after the request reached it answers 502
+or 504, and a 503 from the owner itself is relayed unchanged.
## Receiving webhooks
diff --git a/sdk/javascript/src/errors.ts b/sdk/javascript/src/errors.ts
index a9542fe76..ecdf7941c 100644
--- a/sdk/javascript/src/errors.ts
+++ b/sdk/javascript/src/errors.ts
@@ -119,16 +119,19 @@ export class OpenWANotImplementedError extends OpenWAApiError {}
* straight away prolongs the throttle. A catalog 503 can persist because WhatsApp may never answer
* that query, so bound any retry.
*
- * A throttle turned the request away before it ran, so nothing was sent or applied, and a keyed send
- * frees its `Idempotency-Key` for the retry. A timeout proves nothing: the write may still have been
- * applied, and a keyed send keeps its key taken. The non-idempotent sends (group create, channel
- * create, media send) are deliberately left unbounded by the gateway so a slow WhatsApp reply never
- * answers one, and in a multi-node deployment a forward that fails before reaching the owner node
- * answers 503. A 503 from the owner itself is relayed unchanged and keeps its meaning, so a bounded
- * write such as a group, channel, contact or profile change that timed out may still have been
- * applied; re-read the state before repeating it. A forward that fails after the request was sent
- * answers 502 or 504 instead (a plain `OpenWAApiError`): the owner may already have carried it out,
- * so do not repeat a non-idempotent send on those unchecked.
+ * On a send or a single write, a throttle turned the request away before it ran, so nothing was
+ * sent or applied, and a keyed send frees its `Idempotency-Key` for the retry. A group settings
+ * update with several fields applies them one at a time, so a 503 on a later field, a throttle
+ * included, leaves the earlier ones applied; the message lists them after `already applied:`, so
+ * re-read the settings before retrying, or send one field per request. A timeout proves nothing:
+ * the write may still have been applied, and a keyed send keeps its key taken. The non-idempotent
+ * sends (group create, channel create, media send) are deliberately left unbounded by the gateway
+ * so a slow WhatsApp reply never answers one, and in a multi-node deployment a forward that fails
+ * before reaching the owner node answers 503. A 503 from the owner itself is relayed unchanged and
+ * keeps its meaning, so a bounded write such as a group, channel, contact or profile change that
+ * timed out may still have been applied; re-read the state before repeating it. A forward that
+ * fails after the request was sent answers 502 or 504 instead (a plain `OpenWAApiError`): the owner
+ * may already have carried it out, so do not repeat a non-idempotent send on those unchecked.
*/
export class OpenWAServiceUnavailableError extends OpenWAApiError {}
diff --git a/sdk/php/README.md b/sdk/php/README.md
index 72579315a..3321ed688 100644
--- a/sdk/php/README.md
+++ b/sdk/php/README.md
@@ -78,10 +78,14 @@ seconds when only sends still in flight caused it, the rest of the failure break
(`SEND_PACING_BREAKER_COOLDOWN_MS`, 15 minutes by default) after a run of send failures, otherwise
up to the next UTC day. `getHeaders()` returns the response headers. A 503 does not always prove a
write was never carried out: when WhatsApp timed out, the change may still have been applied, so
-re-read the state before repeating it. A throttle is the exception: it was turned away before it
-ran, so nothing was sent, and a keyed send frees its `Idempotency-Key`. In a routed deployment a
-forward that fails before reaching the owner node answers 503, one that fails after the request
-reached it answers 502 or 504, and a 503 from the owner itself is relayed unchanged.
+re-read the state before repeating it. A throttle on a send or a single write is the exception: it
+was turned away before it ran, so nothing was sent or applied, and a keyed send frees its
+`Idempotency-Key`. A group settings update with several fields applies them one at a time, so a 503
+on a later field, a throttle included, leaves the earlier ones applied; its message lists them after
+`already applied:`, so re-read the settings before retrying, or send one field per request. In a
+routed deployment a forward that fails before reaching the owner node answers 503, one that fails
+after the request reached it answers 502 or 504, and a 503 from the owner itself is relayed
+unchanged.
Guzzle's stream handler, which Guzzle uses on a host without `ext-curl`, throws a plain Guzzle exception
when a gateway stays silent past the timeout, before the response headers on either Guzzle major and, on
diff --git a/sdk/php/src/Exceptions/OpenWAServiceUnavailableException.php b/sdk/php/src/Exceptions/OpenWAServiceUnavailableException.php
index fe41a6361..6f9a8d0e4 100644
--- a/sdk/php/src/Exceptions/OpenWAServiceUnavailableException.php
+++ b/sdk/php/src/Exceptions/OpenWAServiceUnavailableException.php
@@ -14,16 +14,19 @@ namespace OpenWA\Exceptions;
* request straight away prolongs the throttle. A catalog 503 can persist because WhatsApp may never
* answer that query, so bound any retry.
*
- * A throttle turned the request away before it ran, so nothing was sent or applied, and a keyed
- * send frees its Idempotency-Key for the retry. A timeout proves nothing: the write may still have
- * been applied, and a keyed send keeps its key taken. The non-idempotent sends are deliberately
- * left unbounded by the gateway so a slow WhatsApp reply never answers one, and in a multi-node
- * deployment a forward that fails before reaching the owner node answers 503. A 503 from the owner
- * itself is relayed unchanged and keeps its meaning, so a bounded write (group, channel, contact or
- * profile change) that timed out may still have been applied; re-read the state before repeating
- * it. A forward that fails after the request was sent answers 502 or 504 instead (a plain
- * OpenWAApiException): the owner may already have carried it out, so do not repeat a non-idempotent
- * send on those unchecked.
+ * On a send or a single write, a throttle turned the request away before it ran, so nothing was
+ * sent or applied, and a keyed send frees its Idempotency-Key for the retry. A group settings
+ * update with several fields applies them one at a time, so a 503 on a later field, a throttle
+ * included, leaves the earlier ones applied; the message lists them after "already applied:", so
+ * re-read the settings before retrying, or send one field per request. A timeout proves nothing:
+ * the write may still have been applied, and a keyed send keeps its key taken. The non-idempotent
+ * sends are deliberately left unbounded by the gateway so a slow WhatsApp reply never answers one,
+ * and in a multi-node deployment a forward that fails before reaching the owner node answers 503. A
+ * 503 from the owner itself is relayed unchanged and keeps its meaning, so a bounded write (group,
+ * channel, contact or profile change) that timed out may still have been applied; re-read the state
+ * before repeating it. A forward that fails after the request was sent answers 502 or 504 instead
+ * (a plain OpenWAApiException): the owner may already have carried it out, so do not repeat a
+ * non-idempotent send on those unchecked.
*/
class OpenWAServiceUnavailableException extends OpenWAApiException
{
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 11f2b796b..7ec5a3cb2 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -91,10 +91,13 @@ which then comes from the body: a few seconds when only sends still in flight ca
the failure breaker's cooldown (`SEND_PACING_BREAKER_COOLDOWN_MS`, 15 minutes by default) after a
run of send failures, otherwise up to the next UTC day. Every API error also exposes the response
`.headers`. A 503 does not always prove a write was never carried out: when WhatsApp timed out, the
-change may still have been applied, so re-read the state before repeating it. A throttle is the
-exception: it was turned away before it ran, so nothing was sent, and a keyed send frees its
-`Idempotency-Key`. In a routed deployment a forward that fails before reaching the owner node
-answers 503, one that fails after the request reached it answers 502 or 504, and a 503 from the
+change may still have been applied, so re-read the state before repeating it. A throttle on a send
+or a single write is the exception: it was turned away before it ran, so nothing was sent or
+applied, and a keyed send frees its `Idempotency-Key`. A group settings update with several fields
+applies them one at a time, so a 503 on a later field, a throttle included, leaves the earlier ones
+applied; its message lists them after `already applied:`, so re-read the settings before retrying,
+or send one field per request. In a routed deployment a forward that fails before reaching the owner
+node answers 503, one that fails after the request reached it answers 502 or 504, and a 503 from the
owner itself is relayed unchanged.
```python
diff --git a/sdk/python/openwa/errors.py b/sdk/python/openwa/errors.py
index 11fae2492..2bbcca7d4 100644
--- a/sdk/python/openwa/errors.py
+++ b/sdk/python/openwa/errors.py
@@ -137,16 +137,19 @@ class OpenWAServiceUnavailableError(OpenWAApiError):
request straight away prolongs the throttle. A catalog 503 can persist because WhatsApp may
never answer that query, so bound any retry.
- A throttle turned the request away before it ran, so nothing was sent or applied, and a keyed
- send frees its ``Idempotency-Key`` for the retry. A timeout proves nothing: the write may still
- have been applied, and a keyed send keeps its key taken. The non-idempotent sends are
- deliberately left unbounded by the gateway so a slow WhatsApp reply never answers one, and in a
- multi-node deployment a forward that fails before reaching the owner node answers 503. A 503
- from the owner itself is relayed unchanged and keeps its meaning, so a bounded write (group,
- channel, contact or profile change) that timed out may still have been applied; re-read the
- state before repeating it. A forward that fails after the request was sent answers 502 or 504
- instead (a plain OpenWAApiError): the owner may already have carried it out, so do not repeat a
- non-idempotent send on those unchecked.
+ On a send or a single write, a throttle turned the request away before it ran, so nothing was
+ sent or applied, and a keyed send frees its ``Idempotency-Key`` for the retry. A group settings
+ update with several fields applies them one at a time, so a 503 on a later field, a throttle
+ included, leaves the earlier ones applied; the message lists them after ``already applied:``,
+ so re-read the settings before retrying, or send one field per request. A timeout proves
+ nothing: the write may still have been applied, and a keyed send keeps its key taken. The
+ non-idempotent sends are deliberately left unbounded by the gateway so a slow WhatsApp reply
+ never answers one, and in a multi-node deployment a forward that fails before reaching the
+ owner node answers 503. A 503 from the owner itself is relayed unchanged and keeps its meaning,
+ so a bounded write (group, channel, contact or profile change) that timed out may still have
+ been applied; re-read the state before repeating it. A forward that fails after the request was
+ sent answers 502 or 504 instead (a plain OpenWAApiError): the owner may already have carried it
+ out, so do not repeat a non-idempotent send on those unchecked.
"""
diff --git a/src/modules/group/group.service.spec.ts b/src/modules/group/group.service.spec.ts
index f9db33531..ec0a1f51d 100644
--- a/src/modules/group/group.service.spec.ts
+++ b/src/modules/group/group.service.spec.ts
@@ -404,6 +404,23 @@ describe('GroupService', () => {
expect(engine.setGroupInfoAdminsOnly).not.toHaveBeenCalled();
});
+ // The SDKs tell a caller that a throttle 503 applied nothing except on this route, where it can
+ // follow a field that was applied and the message lists that field.
+ it('answers a throttle on a later field with 503 and the fields already applied', async () => {
+ const engine = {
+ setGroupEphemeral: jest.fn().mockResolvedValue(undefined),
+ setGroupMessagesAdminsOnly: jest
+ .fn()
+ .mockRejectedValue(new EngineThrottledError('Updating the group was rate-limited by WhatsApp (code 429)')),
+ };
+ const error = await makeService(engine)
+ .updateGroupSettings('s1', 'g1', { announce: true, ephemeralSeconds: 86400 })
+ .catch((e: unknown) => e);
+ expect((error as HttpException).getStatus()).toBe(503);
+ expect((error as HttpException).message).toContain('(code 429)');
+ expect((error as HttpException).message).toContain('already applied: ephemeralSeconds');
+ });
+
it('propagates a first-field failure unchanged (nothing applied → no partial state to report)', async () => {
const engine = {
setGroupEphemeral: jest.fn().mockRejectedValue(new EngineRefusedError('not a group admin')),