Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(sdk): say how long a global rate-limit 429 can last
Yudhi Armyndharis1feeabcaed46
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex a0ec293f5..83045601a 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. 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. |+| 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 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default); 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. 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) |+| 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 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default); 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. 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. |+| 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 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default); 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 74640df21..9a2afd094 100644--- a/sdk/go/README.md+++ b/sdk/go/README.md@@ -104,13 +104,14 @@ Sentinels: `ErrUnauthorized` (401), `ErrForbidden` (403), `ErrNotFound` (404),`ErrConflict` (409), `ErrRateLimited` (429), `ErrNotImplemented` (501),`ErrServiceUnavailable` (503). 503 is transient, but a catalog 503 can persistbecause 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.+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); 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 b36953519..b52b3b449 100644--- a/sdk/go/errors.go+++ b/sdk/go/errors.go@@ -29,10 +29,12 @@ var (// 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). 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.+ // limiter's 429 lifts when its window expires (seconds for the per-second+ // tier, up to an hour for the hourly tier by default); 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).diff --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 d6a0447ba..72c44346b 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@@ -3,8 +3,9 @@ package com.rmyndharis.openwa.errors;/*** 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:+ * <p>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); 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.*/diff --git a/sdk/javascript/README.md b/sdk/javascript/README.mdindex b1dc3a7ea..9833aea76 100644--- a/sdk/javascript/README.md+++ b/sdk/javascript/README.md@@ -49,12 +49,14 @@ Non-2xx responses throw a typed `OpenWAApiError` subclass (`OpenWAAuthError`,parsed `.body`. Timeouts throw `OpenWATimeoutError`. The SDK does **not**retry — wrap calls with your own backoff if needed. 503 is transient, but acatalog 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.+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); 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 4e120a694..b5b4eb09b 100644--- a/sdk/javascript/src/errors.ts+++ b/sdk/javascript/src/errors.ts@@ -77,7 +77,8 @@ 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. The global rate limiter's 429 clears within seconds; its+ * 429 Too Many Requests — 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); 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.diff --git a/sdk/php/README.md b/sdk/php/README.mdindex b98ecc2b7..c4c2a208f 100644--- a/sdk/php/README.md+++ b/sdk/php/README.md@@ -59,8 +59,9 @@ A non-2xx response throws a typed `OpenWA\Exceptions\OpenWAApiException` subclas`OpenWANotImplementedException` (501), `OpenWAServiceUnavailableException` (503) — eachexposing `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+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); 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 wasnever carried out: a forward that fails after the request reached the owner node answers 502 or 504.diff --git a/sdk/php/src/Exceptions/OpenWARateLimitException.php b/sdk/php/src/Exceptions/OpenWARateLimitException.phpindex 2a862e358..c0e0207ab 100644--- a/sdk/php/src/Exceptions/OpenWARateLimitException.php+++ b/sdk/php/src/Exceptions/OpenWARateLimitException.php@@ -7,10 +7,11 @@ namespace OpenWA\Exceptions;/*** 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.+ * 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); 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/python/README.md b/sdk/python/README.mdindex b921d1b75..1ddbd7918 100644--- a/sdk/python/README.md+++ b/sdk/python/README.md@@ -74,11 +74,12 @@ A non-2xx response raises a typed `OpenWAApiError` subclass — `OpenWAAuthError`OpenWAServiceUnavailableError` (503) — each carrying `.status` and the parsed `.body`. Atimeout raises `OpenWATimeoutError`. 503 is transient, but a catalog 503 can persist becauseWhatsApp 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.+lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly+tier by default); 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.```pythonfrom openwa import OpenWANotFoundErrordiff --git a/sdk/python/openwa/errors.py b/sdk/python/openwa/errors.pyindex 74bafbcaf..33c901bb6 100644--- a/sdk/python/openwa/errors.py+++ b/sdk/python/openwa/errors.py@@ -73,10 +73,11 @@ class OpenWAConflictError(OpenWAApiError):class OpenWARateLimitError(OpenWAApiError):"""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.+ 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); 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."""