Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): describe the WhatsApp throttle 503

Yudhi Armyndharisba56ffed3596
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index c3f3539c2..92251586d 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -371,7 +371,7 @@ On a non-2xx response the SDK throws a typed `OpenWAApiError` subclass carrying
| `OpenWAConflictError` | 409 | Conflict: a conflicting state, typically a session that is not ready, or a keyed send pending or unconfirmed (see `code`). |
| `OpenWARateLimitError` | 429 | Rate limited. The global rate limiter's 429 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. |
| `OpenWANotImplementedError` | 501 | The active engine does not support this operation. |
-| `OpenWAServiceUnavailableError` | 503 | The engine did not confirm in time. Transient, though a catalog 503 can persist because WhatsApp may never answer that query; 501 is permanent. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on. |
+| `OpenWAServiceUnavailableError` | 503 | The gateway could not complete the request now (transport failure, draining, or on Baileys a WhatsApp throttle (429) or timeout (408)). Back off and retry later, though a catalog 503 can persist because WhatsApp may never answer that query; 501 is permanent. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on. |
| `OpenWAApiError` | any other | Generic non-2xx (the base API error, e.g. `400`; also surfaced for unfollowed 3xx redirects). |
| `OpenWATimeoutError` | — | The request exceeded the configured timeout. |
@@ -747,7 +747,7 @@ Every error the SDK raises itself inherits from `OpenWAError`. A non-2xx respons
| `OpenWAConflictError` | HTTP `409`: a conflicting state, typically a session that is not ready, or a keyed send pending or unconfirmed (see `code`) |
| `OpenWARateLimitError` | HTTP `429` — too many requests. The global rate limiter's 429 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and `retry_after_seconds` carries its `Retry-After` header. A 429 whose `code` is `"SEND_PACING_LIMITED"` is usually not transient: do not retry it before `retry_after_seconds`, 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. |
| `OpenWANotImplementedError` | HTTP `501` — active engine doesn't support the operation |
-| `OpenWAServiceUnavailableError` | HTTP `503` — engine did not confirm in time; transient, though a catalog 503 can persist because WhatsApp may never answer that query. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on |
+| `OpenWAServiceUnavailableError` | HTTP `503` — the gateway could not complete the request now (transport failure, draining, or on Baileys a WhatsApp throttle (429) or timeout (408)); back off and retry later, though a catalog 503 can persist because WhatsApp may never answer that query. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on |
| `OpenWAApiError` | any other non-2xx status (incl. unfollowed `3xx`) |
| `OpenWATimeoutError` | request exceeded `timeout` (has a `.timeout` attribute) |
@@ -1102,7 +1102,7 @@ All exceptions the SDK raises itself live in `OpenWA\Exceptions` and descend fro
| `OpenWAConflictException` | `OpenWAApiException` | `409`: a conflicting state, typically a session that is not ready, or a keyed send pending or unconfirmed (see `code`). |
| `OpenWARateLimitException` | `OpenWAApiException` | `429` — rate limited. The global rate limiter's 429 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and `getRetryAfterSeconds()` carries its `Retry-After` header. A 429 whose `getErrorCode()` is `"SEND_PACING_LIMITED"` is usually not transient: do not retry it before `getRetryAfterSeconds()`, 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. |
| `OpenWANotImplementedException` | `OpenWAApiException` | `501` — active engine does not support the operation. |
-| `OpenWAServiceUnavailableException` | `OpenWAApiException` | `503` — engine did not confirm in time; transient, though a catalog 503 can persist because WhatsApp may never answer that query. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on. |
+| `OpenWAServiceUnavailableException` | `OpenWAApiException` | `503` — the gateway could not complete the request now (transport failure, draining, or on Baileys a WhatsApp throttle (429) or timeout (408)); back off and retry later, though a catalog 503 can persist because WhatsApp may never answer that query. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on. |
| `OpenWATimeoutException` | `OpenWAException` | Request exceeded the timeout (`getTimeout(): float`). Not an API error — has no status/body. |
```php
diff --git a/sdk/go/README.md b/sdk/go/README.md
index c59f82db4..b44102cf9 100644
--- a/sdk/go/README.md
+++ b/sdk/go/README.md
@@ -110,26 +110,30 @@ case err != nil:
}
```
-Sentinels: `ErrBadRequest` (400), `ErrUnauthorized` (401),
-`ErrForbidden` (403), `ErrNotFound` (404), `ErrConflict` (409),
-`ErrRateLimited` (429), `ErrNotImplemented` (501),
-`ErrServiceUnavailable` (503). 503 is transient, but 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);
-`APIError.RetryAfter` carries its `Retry-After` header, which `WithRetry` also
-honors. A 429 whose `APIError.Code` is `"SEND_PACING_LIMITED"` is usually not
-transient: do not retry it before `RetryAfter`, 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. `APIError.Header`
-holds the response headers. A timeout surfaces as `*openwa.TimeoutError`. A 503
-does not prove a write was never carried out: the
-engine answers it when WhatsApp did not confirm in time, and the change may still
-have been applied, so re-read the state before repeating it. 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.
+Sentinels: `ErrBadRequest` (400), `ErrUnauthorized` (401), `ErrForbidden` (403),
+`ErrNotFound` (404), `ErrConflict` (409), `ErrRateLimited` (429),
+`ErrNotImplemented` (501), `ErrServiceUnavailable` (503). 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); `APIError.RetryAfter` carries its `Retry-After` header, which
+`WithRetry` also honors. A 429 whose `APIError.Code` is `"SEND_PACING_LIMITED"`
+is usually not transient: do not retry it before `RetryAfter`, 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.
+`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.
## Retries
@@ -141,7 +145,9 @@ lists them): a 500/502/504 can arrive after the message was already sent, so
replaying it could send it twice. A 429 whose body has `code: "SEND_PACING_LIMITED"` is
never retried, whatever the method: its delay is the body's `retryAfterSeconds`, which can be
hours. Backoff is exponential, `Retry-After` is honored, and request bodies are safely rewound
-on each attempt.
+on each attempt. A 503 can be WhatsApp throttling a Baileys send, and the default backoff (three
+retries from 200ms) replays it within about a second and a half; for sends raise `BaseDelay` or lower
+`MaxRetries`, or retry the throttled send yourself later.
```go
client, _ := openwa.New(baseURL, apiKey,
diff --git a/sdk/go/errors.go b/sdk/go/errors.go
index c782baa98..b52f40bea 100644
--- a/sdk/go/errors.go
+++ b/sdk/go/errors.go
@@ -45,18 +45,28 @@ var (
// ErrNotImplemented is returned for a 501 (the active engine does not
// support this operation).
ErrNotImplemented = errors.New("openwa: not implemented")
- // ErrServiceUnavailable is returned for a 503 — a transport failure rather
- // than a refusal: WhatsApp never replied, the socket was down, or the
- // request budget ran out. It is retryable, but a catalog 503 can persist
- // because WhatsApp may never answer that query, so bound any retry. 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 means the engine did not
- // confirm in time, so a bounded write 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 is returned for a 503: the gateway could not
+ // complete the request right now. The path to WhatsApp failed (WhatsApp
+ // never replied, the socket was down, or the request budget ran out), the
+ // gateway is draining or short of a dependency, or, on Baileys, WhatsApp
+ // itself throttled (code 429) or timed out (code 408) the request; a
+ // throttle or timeout names its code in the message. It is retryable, but
+ // back off and retry later instead of at once: 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 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.
ErrServiceUnavailable = errors.New("openwa: service unavailable")
)
diff --git a/sdk/java/README.md b/sdk/java/README.md
index d571f08ef..f9cf86a3e 100644
--- a/sdk/java/README.md
+++ b/sdk/java/README.md
@@ -123,11 +123,11 @@ try {
| `OpenWAConflictError` | 409 | Conflicting state, typically engine not ready, or an idempotency outcome (see `code()`) |
| `OpenWARateLimitError` | 429 | Rate limited |
| `OpenWANotImplementedError` | 501 | Active engine does not support the call |
-| `OpenWAServiceUnavailableError` | 503 | Engine did not confirm in time |
+| `OpenWAServiceUnavailableError` | 503 | Could not complete now: transport failure, draining, or WhatsApp throttle or timeout |
| `OpenWAApiError` | — | Any other non-2xx (carries `.status()`) |
| `OpenWATimeoutError` | — | Request exceeded the configured timeout |
-All extend `OpenWAError` (a `RuntimeException`). 503 is transient, but 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 prove a write was never carried out: the engine answers it when WhatsApp did not confirm in time, and the change may still have been applied, so re-read the state before repeating it. 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 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.
## 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 917246989..d754080d7 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
@@ -4,18 +4,25 @@ import java.util.List;
import java.util.Map;
/**
- * 503 Service Unavailable — a transport failure, not a refusal.
+ * 503 Service Unavailable: the gateway could not complete the request right now.
*
- * <p>The gateway answers this when the engine did not confirm the operation in time: WhatsApp never
- * replied, the socket was down, or the request budget ran out. <b>Retryable</b>, but a catalog 503
- * can persist because WhatsApp may never answer that query, so bound any retry. 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 means the engine did not confirm, so a bounded
- * write such as a group, channel, contact or profile change 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>The path to WhatsApp failed (WhatsApp never replied, the socket was down, or the request budget
+ * ran out), the gateway is draining or short of a dependency, or, on Baileys, WhatsApp itself
+ * throttled (code 429) or timed out (code 408) the request; a throttle or timeout names its code in
+ * the message. <b>Retryable</b>, but back off and retry later instead of at once: 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.
+ *
+ * <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.
*/
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 a275af3c3..d31d084ca 100644
--- a/sdk/javascript/README.md
+++ b/sdk/javascript/README.md
@@ -49,24 +49,29 @@ CommonJS consumers use `require('@rmyndharis/openwa')` identically.
Non-2xx responses throw a typed `OpenWAApiError` subclass (`OpenWAAuthError`,
`OpenWAForbiddenError`, `OpenWANotFoundError`, `OpenWAConflictError`,
`OpenWARateLimitError`, `OpenWANotImplementedError`,
-`OpenWAServiceUnavailableError` for 503), each carrying `.status` and the
-parsed `.body`. Timeouts throw `OpenWATimeoutError`. The SDK does **not**
-retry — wrap calls with your own backoff if needed. 503 is transient, but 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
+`OpenWAServiceUnavailableError` for 503), each carrying `.status` and the parsed
+`.body`. Timeouts throw `OpenWATimeoutError`. The SDK does **not** retry — wrap
+calls with your own backoff if needed. 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. Every API error also exposes the
-response `.headers`. A 503 does not prove a write was never carried out: the
-engine answers it when WhatsApp did not confirm in time,
-and the change may still have been applied, so re-read the state before
-repeating it. 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.
+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.
## Receiving webhooks
diff --git a/sdk/javascript/src/errors.ts b/sdk/javascript/src/errors.ts
index 4f2132a36..a9542fe76 100644
--- a/sdk/javascript/src/errors.ts
+++ b/sdk/javascript/src/errors.ts
@@ -111,19 +111,24 @@ export class OpenWARateLimitError extends OpenWAApiError {}
export class OpenWANotImplementedError extends OpenWAApiError {}
/**
- * 503 Service Unavailable — a transport failure, not a refusal. The gateway answers this when the
- * engine did not confirm the operation in time: WhatsApp never replied, the socket was down, or the
- * request budget ran out. **Retryable**, but a catalog 503 can persist because WhatsApp may never
- * answer that query, so bound any retry.
+ * 503 Service Unavailable: the gateway could not complete the request right now. The path to
+ * WhatsApp failed (WhatsApp never replied, the socket was down, or the request budget ran out), the
+ * gateway is draining or short of a dependency, or, on Baileys, WhatsApp itself throttled (code 429)
+ * or timed out (code 408) the request; a throttle or timeout names its code in the message.
+ * **Retryable**, but back off and retry later instead of at once: 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.
*
- * Not every 503 is safe to repeat blindly: 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 means the engine did not confirm, so a
- * bounded write such as a group, channel, contact or profile change 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.
+ * 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.
*/
export class OpenWAServiceUnavailableError extends OpenWAApiError {}
diff --git a/sdk/php/README.md b/sdk/php/README.md
index 92fa78522..72579315a 100644
--- a/sdk/php/README.md
+++ b/sdk/php/README.md
@@ -63,19 +63,23 @@ The optional `defaultHeaders` map accepts strings, scalar values, null, and non-
A non-2xx response throws a typed `OpenWA\Exceptions\OpenWAApiException` subclass —
`OpenWAAuthException` (401), `OpenWAForbiddenException` (403), `OpenWANotFoundException` (404),
-`OpenWAConflictException` (409), `OpenWARateLimitException` (429),
-`OpenWANotImplementedException` (501), `OpenWAServiceUnavailableException` (503) — each
-exposing `getStatus()` and the parsed `getBody()`. A timeout throws `OpenWATimeoutException`.
-503 is transient, but 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 `getRetryAfterSeconds()`
-carries its `Retry-After` header. A 429 whose `getErrorCode()` is `"SEND_PACING_LIMITED"` is usually
-not transient: do not retry it before `getRetryAfterSeconds()`, 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
+`OpenWAConflictException` (409), `OpenWARateLimitException` (429), `OpenWANotImplementedException`
+(501), `OpenWAServiceUnavailableException` (503) — each exposing `getStatus()` and the parsed
+`getBody()`. A timeout throws `OpenWATimeoutException`. 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 `getRetryAfterSeconds()` carries its
+`Retry-After` header. A 429 whose `getErrorCode()` is `"SEND_PACING_LIMITED"` is usually not
+transient: do not retry it before `getRetryAfterSeconds()`, 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. `getHeaders()` returns the response headers. A 503 does not prove a write
-was never carried out: the engine answers it when WhatsApp did not confirm in time, and the change
-may still have been applied, so re-read the state before repeating it. In a routed deployment a
+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.
diff --git a/sdk/php/src/Exceptions/OpenWAServiceUnavailableException.php b/sdk/php/src/Exceptions/OpenWAServiceUnavailableException.php
index cf357aaab..fe41a6361 100644
--- a/sdk/php/src/Exceptions/OpenWAServiceUnavailableException.php
+++ b/sdk/php/src/Exceptions/OpenWAServiceUnavailableException.php
@@ -5,18 +5,25 @@ declare(strict_types=1);
namespace OpenWA\Exceptions;
/**
- * 503 Service Unavailable — a transport failure, not a refusal.
+ * 503 Service Unavailable: the gateway could not complete the request right now.
*
- * The gateway answers this when the engine did not confirm the operation in time: WhatsApp never
- * replied, the socket was down, or the request budget ran out. Retryable, but a catalog 503 can
- * persist because WhatsApp may never answer that query, so bound any retry. 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 means the engine did not confirm, so a bounded
- * write (group, channel, contact or profile change) 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.
+ * The path to WhatsApp failed (WhatsApp never replied, the socket was down, or the request budget
+ * ran out), the gateway is draining or short of a dependency, or, on Baileys, WhatsApp itself
+ * throttled (code 429) or timed out (code 408) the request; a throttle or timeout names its code in
+ * the message. Retryable, but back off and retry later instead of at once: 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 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.
*/
class OpenWAServiceUnavailableException extends OpenWAApiException
{
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 895eacda1..11f2b796b 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -77,21 +77,25 @@ to sessions or chats, so read it with `get`.
A non-2xx response raises a typed `OpenWAApiError` subclass — `OpenWAAuthError` (401),
`OpenWAForbiddenError` (403), `OpenWANotFoundError` (404), `OpenWAConflictError` (409),
-`OpenWARateLimitError` (429), `OpenWANotImplementedError` (501),
-`OpenWAServiceUnavailableError` (503) — each carrying `.status` and the parsed `.body`. A
-timeout raises `OpenWATimeoutError`. 503 is transient, but 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 `.retry_after_seconds` carries its `Retry-After` header. A 429 whose
-`.code` is `"SEND_PACING_LIMITED"` is usually not transient: do not retry it before
-`.retry_after_seconds`, 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. Every API
-error also exposes the response `.headers`. A 503 does not prove a write was never carried out: the
-engine answers it when WhatsApp did not confirm in time, and the change may still have been applied,
-so re-read the state before repeating it. 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.
+`OpenWARateLimitError` (429), `OpenWANotImplementedError` (501), `OpenWAServiceUnavailableError`
+(503) — each carrying `.status` and the parsed `.body`. A timeout raises `OpenWATimeoutError`. 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
+`.retry_after_seconds` carries its `Retry-After` header. A 429 whose `.code` is
+`"SEND_PACING_LIMITED"` is usually not transient: do not retry it before `.retry_after_seconds`,
+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. 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.
```python
from openwa import OpenWANotFoundError
diff --git a/sdk/python/openwa/errors.py b/sdk/python/openwa/errors.py
index 21e02b84a..11fae2492 100644
--- a/sdk/python/openwa/errors.py
+++ b/sdk/python/openwa/errors.py
@@ -128,18 +128,25 @@ class OpenWANotImplementedError(OpenWAApiError):
class OpenWAServiceUnavailableError(OpenWAApiError):
- """503 Service Unavailable -- a transport failure, not a refusal.
-
- The gateway answers this when the engine did not confirm the operation in time: WhatsApp never
- replied, the socket was down, or the request budget ran out. Retryable, but a catalog 503 can
- persist because WhatsApp may never answer that query, so bound any retry. 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 means the engine did not confirm, so a
- bounded write (group, channel, contact or profile change) 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.
+ """503 Service Unavailable: the gateway could not complete the request right now.
+
+ The path to WhatsApp failed (WhatsApp never replied, the socket was down, or the request budget
+ ran out), the gateway is draining or short of a dependency, or, on Baileys, WhatsApp itself
+ throttled (code 429) or timed out (code 408) the request; a throttle or timeout names its code
+ in the message. Retryable, but back off and retry later instead of at once: 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 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.
"""