Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): name the failure breaker in the pacing 429 wait

Yudhi Armyndharisb45278595070
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index f736f84b2..284f20e6c 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -360,17 +360,17 @@ Media bodies share the `SendMediaRequest` shape: `{ chatId, url? | base64?, mime
On 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`). An API error also carries `.code` (the body's `code`, e.g. `SEND_PACING_LIMITED`), `.retryAfterSeconds` (the body's `retryAfterSeconds`, else the `Retry-After` header) and `.headers` (the response `Headers`).
-| Error class | HTTP status | Meaning |
-| ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `OpenWAAuthError` | 401 | Missing or invalid API key. |
-| `OpenWAForbiddenError` | 403 | The key's role or scope refuses the call (e.g. an OPERATOR-only route, or a session, IP or chat outside the key's allow-lists), or WhatsApp itself refused the operation (for example, missing group admin rights). |
-| `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), 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, 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. |
-| `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 or scope refuses the call (e.g. an OPERATOR-only route, or a session, IP or chat outside the key's allow-lists), or WhatsApp itself refused the operation (for example, missing group admin rights). |
+| `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), 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. |
+| `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. |
```typescript
import {
@@ -735,17 +735,17 @@ Resources are accessed as properties on the client (e.g. `client.messages`). All
Every 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), plus `.code` (the body's `code`), `.retry_after_seconds` (the body's `retryAfterSeconds`, else the `Retry-After` header) and `.headers` (the response headers).
-| Exception | Trigger |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `OpenWAAuthError` | HTTP `401` — missing or invalid API key |
-| `OpenWAForbiddenError` | HTTP `403` — the key's role or scope (session, IP or chat allow-list) refuses the call, or WhatsApp itself refused the operation (for example, missing group admin rights) |
-| `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), 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, 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 |
-| `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` — the key's role or scope (session, IP or chat allow-list) refuses the call, or WhatsApp itself refused the operation (for example, missing group admin rights) |
+| `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), 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 |
+| `OpenWAApiError` | any other non-2xx status (incl. unfollowed `3xx`) |
+| `OpenWATimeoutError` | request exceeded `timeout` (has a `.timeout` attribute) |
```python
from openwa import (
@@ -1087,18 +1087,18 @@ All payloads are associative arrays; all listed methods are synchronous and retu
All 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`), plus the body's `code` (`getErrorCode(): ?string`), the retry delay in seconds from the body's `retryAfterSeconds` or the `Retry-After` header (`getRetryAfterSeconds(): ?int`) and the response headers (`getHeaders(): array`).
-| 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` — the key's role or scope refuses the call (e.g. operator-only endpoint, or a session, IP or chat outside its allow-lists), or WhatsApp itself refused the operation (for example, missing group admin rights). |
-| `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), 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, 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. |
-| `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` — the key's role or scope refuses the call (e.g. operator-only endpoint, or a session, IP or chat outside its allow-lists), or WhatsApp itself refused the operation (for example, missing group admin rights). |
+| `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), 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. |
+| `OpenWATimeoutException` | `OpenWAException` | Request exceeded the timeout (`getTimeout(): float`). Not an API error — has no status/body. |
```php
<?php
diff --git a/sdk/go/README.md b/sdk/go/README.md
index 35cefa45a..89f6a7100 100644
--- a/sdk/go/README.md
+++ b/sdk/go/README.md
@@ -126,9 +126,11 @@ 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, 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
+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
diff --git a/sdk/go/errors.go b/sdk/go/errors.go
index 56f38ffcd..253707b86 100644
--- a/sdk/go/errors.go
+++ b/sdk/go/errors.go
@@ -37,7 +37,9 @@ var (
// carries its Retry-After header, which WithRetry also honors. A 429 whose
// 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, otherwise up to the next UTC day.
+ // 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.
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/README.md b/sdk/java/README.md
index f006bd90b..437f1030c 100644
--- a/sdk/java/README.md
+++ b/sdk/java/README.md
@@ -135,7 +135,7 @@ try {
| `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, 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 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.
## Receiving webhooks
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.java
index 90e75abcd..585c3da46 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
@@ -10,8 +10,9 @@ import java.util.Map;
* up to an hour for the hourly tier by default), and {@link #retryAfterSeconds()} carries its
* {@code Retry-After} header. A 429 whose {@link #code()} is {@code "SEND_PACING_LIMITED"} is
* usually not transient: do not retry it before {@link #retryAfterSeconds()}, which then comes from
- * the body: a few seconds when only sends still in flight caused it, otherwise up to the next UTC
- * day.
+ * the body: a few seconds when only sends still in flight caused it, the rest of the failure
+ * breaker's cooldown ({@code SEND_PACING_BREAKER_COOLDOWN_MS}, 15 minutes by default) after a run of
+ * send failures, otherwise up to the next UTC day.
*/
public class OpenWARateLimitError extends OpenWAApiError {
public OpenWARateLimitError(String message, int status, Object body, String errorKind) {
diff --git a/sdk/javascript/README.md b/sdk/javascript/README.md
index ca2064612..98f2731f3 100644
--- a/sdk/javascript/README.md
+++ b/sdk/javascript/README.md
@@ -67,9 +67,11 @@ any retry. A 429 from the global rate limiter lifts when its window expires
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, 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,
+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
diff --git a/sdk/javascript/src/errors.ts b/sdk/javascript/src/errors.ts
index 73230121d..0b1645aaf 100644
--- a/sdk/javascript/src/errors.ts
+++ b/sdk/javascript/src/errors.ts
@@ -102,7 +102,9 @@ export class OpenWAConflictError extends OpenWAApiError {}
* 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 with `code: '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, otherwise up to the next UTC day.
+ * 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.
*/
export class OpenWARateLimitError extends OpenWAApiError {}
/** 501 Not Implemented — the active engine does not support this operation. */
diff --git a/sdk/php/README.md b/sdk/php/README.md
index 036c13f8c..097690ccd 100644
--- a/sdk/php/README.md
+++ b/sdk/php/README.md
@@ -75,12 +75,13 @@ so bound any retry. A 429 from the global rate limiter lifts when its window exp
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, 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 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.
+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
+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.
```php
use OpenWA\Exceptions\OpenWANotFoundException;
diff --git a/sdk/php/src/Exceptions/OpenWARateLimitException.php b/sdk/php/src/Exceptions/OpenWARateLimitException.php
index f95cb9e28..eb876c071 100644
--- a/sdk/php/src/Exceptions/OpenWARateLimitException.php
+++ b/sdk/php/src/Exceptions/OpenWARateLimitException.php
@@ -12,8 +12,9 @@ namespace OpenWA\Exceptions;
* 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, otherwise up to the next
- * UTC day.
+ * 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.
*/
class OpenWARateLimitException extends OpenWAApiException
{
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 98367872e..a0064f87f 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -90,12 +90,13 @@ lifts when its window expires (seconds for the per-second tier, up to an hour fo
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, 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.
+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.
```python
from openwa import OpenWANotFoundError
diff --git a/sdk/python/openwa/errors.py b/sdk/python/openwa/errors.py
index 0edc45762..c5bfffe10 100644
--- a/sdk/python/openwa/errors.py
+++ b/sdk/python/openwa/errors.py
@@ -107,8 +107,9 @@ class OpenWARateLimitError(OpenWAApiError):
``retry_after_seconds`` carries its Retry-After header. A 429 with code
"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, otherwise up to the next UTC
- day.
+ 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.
"""