Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(sdk): stop calling every 429 transient
Yudhi Armyndharisb14c5562c539
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex afb9dc27e..a0ec293f5 100644--- a/docs/18-sdk-design.md+++ b/docs/18-sdk-design.md@@ -355,17 +355,17 @@ Media bodies share the `SendMediaRequest` shape: `{ chatId, url? | base64?, mimeOn a non-2xx response the SDK throws a typed `OpenWAApiError` subclass carrying `.status` (HTTP status), `.body` (parsed JSON error envelope, or raw text), and `.errorKind` (the NestJS `error` field, `undefined` when the gateway omits it — which is the norm for a validation rejection in production, where `disableErrorMessages` is on). All error classes extend `OpenWAError` and are exported, so they are `instanceof`-checkable. A timeout throws `OpenWATimeoutError`, which extends `OpenWAError` directly (not `OpenWAApiError`).-| Error class | HTTP status | Meaning |-| ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `OpenWAAuthError` | 401 | Missing or invalid API key. |-| `OpenWAForbiddenError` | 403 | The key's role is insufficient (e.g. an OPERATOR-only route). |-| `OpenWANotFoundError` | 404 | Resource not found. |-| `OpenWAConflictError` | 409 | Conflict — typically the engine is not ready. |-| `OpenWARateLimitError` | 429 | Rate limited. |-| `OpenWANotImplementedError` | 501 | The active engine does not support this operation. |-| `OpenWAServiceUnavailableError` | 503 | The engine did not confirm in time. Transient, like 429 (honor `Retry-After`), though a catalog 503 can persist because WhatsApp may never answer that query; 501 is permanent. In a routed deployment a forwarded request answers 503 only when the owner node was never reached; 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. |+| Error class | HTTP status | Meaning |+| ------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `OpenWAAuthError` | 401 | Missing or invalid API key. |+| `OpenWAForbiddenError` | 403 | The key's role is insufficient (e.g. an OPERATOR-only route). |+| `OpenWANotFoundError` | 404 | Resource not found. |+| `OpenWAConflictError` | 409 | Conflict — typically the engine is not ready. |+| `OpenWARateLimitError` | 429 | Rate limited. The global rate limiter's 429 clears within seconds; its delay is only in the `Retry-After` response header, which the error does not carry. A 429 whose body has `code: "SEND_PACING_LIMITED"` is not transient: do not retry it before the body's `retryAfterSeconds`, which can be hours. |+| `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 forwarded request answers 503 only when the owner node was never reached; 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. |```typescriptimport {@@ -726,17 +726,17 @@ Resources are accessed as properties on the client (e.g. `client.messages`). AllEvery error inherits from `OpenWAError`. A non-2xx response raises an `OpenWAApiError` (or a more specific subclass picked by status); a timeout raises `OpenWATimeoutError`. The API-error classes carry `.status` (HTTP code), `.body` (parsed JSON or raw text), and `.error_kind` (the NestJS `error` field).-| Exception | Trigger |-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `OpenWAAuthError` | HTTP `401` — missing or invalid API key |-| `OpenWAForbiddenError` | HTTP `403` — insufficient role |-| `OpenWANotFoundError` | HTTP `404` — resource not found |-| `OpenWAConflictError` | HTTP `409` — typically engine-not-ready |-| `OpenWARateLimitError` | HTTP `429` — too many requests |-| `OpenWANotImplementedError` | HTTP `501` — active engine doesn't support the operation |-| `OpenWAServiceUnavailableError` | HTTP `503` — engine did not confirm in time; transient, like 429 (honor `Retry-After`), though a catalog 503 can persist because WhatsApp may never answer that query. In a routed deployment a forwarded request answers 503 only when the owner node was never reached; 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) |+| Exception | Trigger |+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `OpenWAAuthError` | HTTP `401` — missing or invalid API key |+| `OpenWAForbiddenError` | HTTP `403` — insufficient role |+| `OpenWANotFoundError` | HTTP `404` — resource not found |+| `OpenWAConflictError` | HTTP `409` — typically engine-not-ready |+| `OpenWARateLimitError` | HTTP `429` — too many requests. The global rate limiter's 429 clears within seconds; its delay is only in the `Retry-After` response header, which the error does not carry. A 429 whose body has `code: "SEND_PACING_LIMITED"` is not transient: do not retry it before the body's `retryAfterSeconds`, which can be hours. |+| `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 forwarded request answers 503 only when the owner node was never reached; 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) |```pythonfrom openwa import (@@ -1075,18 +1075,18 @@ All payloads are associative arrays; all listed methods are synchronous and retuAll exceptions live in `OpenWA\Exceptions` and descend from `OpenWAException` (which extends PHP's `\Exception`). Any non-2xx response is raised as an `OpenWAApiException`; the static `classify()` factory picks the most specific subclass by status code. An `OpenWAApiException` carries the HTTP status (`getStatus(): int`), the parsed error body (`getBody(): mixed`), and the NestJS `error` kind when present (`getErrorKind(): ?string`).-| Exception | Extends | Trigger |-| ----------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `OpenWAException` | `\Exception` | Base for all SDK errors (also thrown for missing `baseUrl`/`apiKey`). |-| `OpenWAApiException` | `OpenWAException` | Any non-2xx (including unfollowed 3xx and other 4xx/5xx). |-| `OpenWAAuthException` | `OpenWAApiException` | `401` — missing/invalid API key. |-| `OpenWAForbiddenException` | `OpenWAApiException` | `403` — insufficient role (e.g. operator-only endpoint). |-| `OpenWANotFoundException` | `OpenWAApiException` | `404` — resource not found. |-| `OpenWAConflictException` | `OpenWAApiException` | `409` — conflict (e.g. engine not ready). |-| `OpenWARateLimitException` | `OpenWAApiException` | `429` — rate limited. |-| `OpenWANotImplementedException` | `OpenWAApiException` | `501` — active engine does not support the operation. |-| `OpenWAServiceUnavailableException` | `OpenWAApiException` | `503` — engine did not confirm in time; transient, like 429 (honor `Retry-After`), though a catalog 503 can persist because WhatsApp may never answer that query. In a routed deployment a forwarded request answers 503 only when the owner node was never reached; 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. |+| Exception | Extends | Trigger |+| ----------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `OpenWAException` | `\Exception` | Base for all SDK errors (also thrown for missing `baseUrl`/`apiKey`). |+| `OpenWAApiException` | `OpenWAException` | Any non-2xx (including unfollowed 3xx and other 4xx/5xx). |+| `OpenWAAuthException` | `OpenWAApiException` | `401` — missing/invalid API key. |+| `OpenWAForbiddenException` | `OpenWAApiException` | `403` — insufficient role (e.g. operator-only endpoint). |+| `OpenWANotFoundException` | `OpenWAApiException` | `404` — resource not found. |+| `OpenWAConflictException` | `OpenWAApiException` | `409` — conflict (e.g. engine not ready). |+| `OpenWARateLimitException` | `OpenWAApiException` | `429` — rate limited. The global rate limiter's 429 clears within seconds; its delay is only in the `Retry-After` response header, which the error does not carry. A 429 whose body has `code: "SEND_PACING_LIMITED"` is not transient: do not retry it before the body's `retryAfterSeconds`, which can be hours. |+| `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 forwarded request answers 503 only when the owner node was never reached; 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<?phpdiff --git a/sdk/go/README.md b/sdk/go/README.mdindex cdefd2f93..74640df21 100644--- a/sdk/go/README.md+++ b/sdk/go/README.md@@ -102,12 +102,15 @@ case err != nil:Sentinels: `ErrUnauthorized` (401), `ErrForbidden` (403), `ErrNotFound` (404),`ErrConflict` (409), `ErrRateLimited` (429), `ErrNotImplemented` (501),-`ErrServiceUnavailable` (503). 429 (honor `Retry-After`) and 503 are the-transient statuses, but a catalog 503 can persist because WhatsApp may never-answer that query, so bound any retry. A timeout-surfaces as `*openwa.TimeoutError`. In a routed deployment only 503 proves-the request was never carried out: a forward that fails after the request-reached the owner node answers 502 or 504.+`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 clears within seconds; its delay is only in the+`Retry-After` response header, which `APIError` does not carry but `WithRetry`+honors. A 429 whose body has `code: "SEND_PACING_LIMITED"` is not transient:+do not retry it before the body's `retryAfterSeconds`, which can be hours. A+timeout surfaces as `*openwa.TimeoutError`. In a routed deployment only 503+proves the request was never carried out: a forward that fails after the+request reached the owner node answers 502 or 504.## Retriesdiff --git a/sdk/go/errors.go b/sdk/go/errors.goindex a9e1f9b8c..b36953519 100644--- a/sdk/go/errors.go+++ b/sdk/go/errors.go@@ -28,22 +28,25 @@ var (ErrNotFound = errors.New("openwa: not found")// ErrConflict is returned for a 409 (typically an engine-not-ready condition).ErrConflict = errors.New("openwa: conflict")- // ErrRateLimited is returned for a 429 (too many requests).+ // ErrRateLimited is returned for a 429 (too many requests). The global rate+ // limiter's 429 clears within seconds; its delay is only in the Retry-After+ // response header, which APIError does not carry but WithRetry honors. A+ // 429 whose Body has code "SEND_PACING_LIMITED" is not transient: do not+ // retry it before the body's retryAfterSeconds, which can be hours.ErrRateLimited = errors.New("openwa: rate limited")// 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, as is ErrRateLimited (honor- // its Retry-After), 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 forwarded request- // answers 503 only when the owner node was never reached. 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.+ // 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+ // forwarded request answers 503 only when the owner node was never reached.+ // 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 528a7654a..5f708d09b 100644--- a/sdk/java/README.md+++ b/sdk/java/README.md@@ -108,7 +108,7 @@ try {| `OpenWAApiError` | — | Any other non-2xx (carries `.status()`) || `OpenWATimeoutError` | — | Request exceeded the configured timeout |-All extend `OpenWAError` (a `RuntimeException`). 429 (honor `Retry-After`) and 503 are the transient statuses, but a catalog 503 can persist because WhatsApp may never answer that query, so bound any retry. In a routed deployment only 503 proves the request was never carried out: a forward that fails after the request reached the owner node answers 502 or 504.+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 clears within seconds; its delay is only in the `Retry-After` response header, which the error does not carry. A 429 whose body has `code: "SEND_PACING_LIMITED"` is not transient: do not retry it before the body's `retryAfterSeconds`, which can be hours. In a routed deployment only 503 proves the request was never carried out: a forward that fails after the request reached the owner node answers 502 or 504.## Reliability & securitydiff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWARateLimitError.java b/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWARateLimitError.javaindex 48ad68df3..d6a0447ba 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWARateLimitError.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWARateLimitError.java@@ -1,6 +1,13 @@package com.rmyndharis.openwa.errors;-/** 429 Too Many Requests — rate limited. */+/**+ * 429 Too Many Requests — rate limited.+ *+ * <p>The global rate limiter's 429 clears within seconds; its delay is only in the {@code+ * Retry-After} response header, which this error does not carry. A 429 whose body has {@code code:+ * "SEND_PACING_LIMITED"} is not transient: do not retry it before the body's {@code+ * retryAfterSeconds}, which can be hours.+ */public class OpenWARateLimitError extends OpenWAApiError {public OpenWARateLimitError(String message, int status, Object body, String errorKind) {super(message, status, body, errorKind);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.javaindex fc90c17b8..b1c6cfded 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,13 +4,13 @@ package com.rmyndharis.openwa.errors;* 503 Service Unavailable — a transport failure, not a refusal.** <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>, as is a 429 (honor- * its {@code Retry-After}), 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 forwarded request- * answers 503 only when the owner node was never reached. 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.+ * 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 forwarded request answers 503 only when the owner node was never+ * reached. 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 221d096cb..b1dc3a7ea 100644--- a/sdk/javascript/README.md+++ b/sdk/javascript/README.md@@ -42,17 +42,19 @@ CommonJS consumers use `require('@rmyndharis/openwa')` identically.## Errors-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. 429 (honor `Retry-After`) and 503 are the transient-statuses, but a catalog 503 can persist because WhatsApp may never answer-that query, so bound any retry. In a routed deployment only 503 proves the request was-never carried out: a forward that fails after the request reached the owner-node answers 502 or 504.+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 clears within seconds; its delay+is only in the `Retry-After` response header, which the error does not carry.+A 429 whose body has `code: "SEND_PACING_LIMITED"` is not transient: do not+retry it before the body's `retryAfterSeconds`, which can be hours. In a+routed deployment only 503 proves the request was never carried out: a forward+that fails after the request reached the owner node answers 502 or 504.## Releasingdiff --git a/sdk/javascript/src/errors.ts b/sdk/javascript/src/errors.tsindex 4ecd6c675..4e120a694 100644--- a/sdk/javascript/src/errors.ts+++ b/sdk/javascript/src/errors.ts@@ -76,7 +76,12 @@ export class OpenWAForbiddenError extends OpenWAApiError {}export class OpenWANotFoundError extends OpenWAApiError {}/** 409 Conflict — typically an {@link EngineNotReadyError} from the backend. */export class OpenWAConflictError extends OpenWAApiError {}-/** 429 Too Many Requests — rate limited. */+/**+ * 429 Too Many Requests — rate limited. The global rate limiter's 429 clears within seconds; its+ * delay is only in the `Retry-After` response header, which this error does not carry. A 429 whose+ * `body` has `code: 'SEND_PACING_LIMITED'` is not transient: do not retry it before+ * `body.retryAfterSeconds`, which can be hours.+ */export class OpenWARateLimitError extends OpenWAApiError {}/** 501 Not Implemented — the active engine does not support this operation. */export class OpenWANotImplementedError extends OpenWAApiError {}@@ -84,8 +89,8 @@ 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**, as is a 429 (honor its `Retry-After`), but a catalog 503 can- * persist because WhatsApp may never answer that query, so bound any retry.+ * request budget ran out. **Retryable**, but 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 answersdiff --git a/sdk/php/README.md b/sdk/php/README.mdindex 88c54a0db..b98ecc2b7 100644--- a/sdk/php/README.md+++ b/sdk/php/README.md@@ -57,12 +57,13 @@ A non-2xx response throws a typed `OpenWA\Exceptions\OpenWAApiException` subclas`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`. 429 (honor `Retry-After`) and 503 are the transient-statuses, but a catalog 503 can persist because WhatsApp may never answer that query, so bound-any retry. In a routed deployment only 503 proves the request-was never carried out: a forward that fails after the request reached the owner node answers-502 or 504.+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 clears within seconds; its delay is only+in the `Retry-After` response header, which the error does not carry. A 429 whose body has+`code: "SEND_PACING_LIMITED"` is not transient: do not retry it before the body's+`retryAfterSeconds`, which can be hours. In a routed deployment only 503 proves the request was+never carried out: a forward that fails after the request reached the owner node answers 502 or 504.```phpuse OpenWA\Exceptions\OpenWANotFoundException;diff --git a/sdk/php/src/Exceptions/OpenWARateLimitException.php b/sdk/php/src/Exceptions/OpenWARateLimitException.phpindex e4aa0e32e..2a862e358 100644--- a/sdk/php/src/Exceptions/OpenWARateLimitException.php+++ b/sdk/php/src/Exceptions/OpenWARateLimitException.php@@ -4,7 +4,14 @@ declare(strict_types=1);namespace OpenWA\Exceptions;-/** 429 Too Many Requests — rate limited. */+/**+ * 429 Too Many Requests — rate limited.+ *+ * The global rate limiter's 429 clears within seconds; its delay is only in the Retry-After+ * response header, which this exception does not carry. A 429 whose body has+ * code "SEND_PACING_LIMITED" is not transient: do not retry it before the body's+ * retryAfterSeconds, which can be hours.+ */class OpenWARateLimitException extends OpenWAApiException{}diff --git a/sdk/php/src/Exceptions/OpenWAServiceUnavailableException.php b/sdk/php/src/Exceptions/OpenWAServiceUnavailableException.phpindex e2da8ef2a..13677dfff 100644--- a/sdk/php/src/Exceptions/OpenWAServiceUnavailableException.php+++ b/sdk/php/src/Exceptions/OpenWAServiceUnavailableException.php@@ -8,13 +8,13 @@ namespace OpenWA\Exceptions;* 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, as is a 429 (honor its- * Retry-After), 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 forwarded request answers 503- * only when the owner node was never reached. 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.+ * 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 forwarded request answers 503 only when the owner node was never+ * reached. 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 93fd522e5..b921d1b75 100644--- a/sdk/python/README.md+++ b/sdk/python/README.md@@ -71,10 +71,12 @@ for hit in res["hits"]: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`. 429 (honor `Retry-After`) and-503 are the transient statuses, but a catalog 503 can persist because WhatsApp may never answer-that query, so bound any retry. In a routed deployment only+`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+clears within seconds; its delay is only in the `Retry-After` response header, which the error+does not carry. A 429 whose body has `code: "SEND_PACING_LIMITED"` is not transient: do not+retry it before the body's `retryAfterSeconds`, which can be hours. In a routed deployment only503 proves the request was never carried out: a forward that fails after the request reachedthe owner node answers 502 or 504.diff --git a/sdk/python/openwa/errors.py b/sdk/python/openwa/errors.pyindex 165387ffd..74bafbcaf 100644--- a/sdk/python/openwa/errors.py+++ b/sdk/python/openwa/errors.py@@ -71,7 +71,13 @@ class OpenWAConflictError(OpenWAApiError):class OpenWARateLimitError(OpenWAApiError):- """429 Too Many Requests."""+ """429 Too Many Requests.++ The global rate limiter's 429 clears within seconds; its delay is only in the Retry-After+ response header, which this error does not carry. A 429 whose body has+ code "SEND_PACING_LIMITED" is not transient: do not retry it before the body's+ retryAfterSeconds, which can be hours.+ """class OpenWANotImplementedError(OpenWAApiError):@@ -82,13 +88,13 @@ 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, as is a 429 (honor its- Retry-After), 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 forwarded request answers 503- only when the owner node was never reached. 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.+ 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 forwarded request answers 503 only when the owner node+ was never reached. 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."""