Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(sdk): describe the WhatsApp throttle 503
Yudhi Armyndharisba56ffed3596
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex 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. |```phpdiff --git a/sdk/go/README.md b/sdk/go/README.mdindex 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, soreplaying it could send it twice. A 429 whose body has `code: "SEND_PACING_LIMITED"` isnever retried, whatever the method: its delay is the body's `retryAfterSeconds`, which can behours. 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.```goclient, _ := openwa.New(baseURL, apiKey,diff --git a/sdk/go/errors.go b/sdk/go/errors.goindex 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.mdindex 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 webhooksdiff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWAServiceUnavailableError.java b/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWAServiceUnavailableError.javaindex 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.mdindex 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 sendfailures, 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 webhooksdiff --git a/sdk/javascript/src/errors.ts b/sdk/javascript/src/errors.tsindex 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.mdindex 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 aforward that fails before reaching the owner node answers 503, one that fails after the requestreached 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.phpindex 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.mdindex 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.```pythonfrom openwa import OpenWANotFoundErrordiff --git a/sdk/python/openwa/errors.py b/sdk/python/openwa/errors.pyindex 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."""