Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): stop reading a 503 as proof a write never ran in Java and JS

Yudhi Armyndharis5c5d00eb2fbe
diff --git a/sdk/java/README.md b/sdk/java/README.md
index 01af5fe43..c6de4bfe8 100644
--- a/sdk/java/README.md
+++ b/sdk/java/README.md
@@ -125,7 +125,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 not transient: do not retry it before `retryAfterSeconds()`, which then comes from the body and can be hours. `headers()` returns the response headers. 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 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 not transient: do not retry it before `retryAfterSeconds()`, which then comes from the body and can be hours. `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.
## Reliability & security
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWAServiceUnavailableError.java b/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWAServiceUnavailableError.java
index 072210023..917246989 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
@@ -10,10 +10,12 @@ import java.util.Map;
* 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.
+ * 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.
*/
public class OpenWAServiceUnavailableError extends OpenWAApiError {
public OpenWAServiceUnavailableError(String message, int status, Object body, String errorKind) {
diff --git a/sdk/javascript/README.md b/sdk/javascript/README.md
index 540776900..78e6c5855 100644
--- a/sdk/javascript/README.md
+++ b/sdk/javascript/README.md
@@ -54,9 +54,12 @@ 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 not transient: do not retry it before
`.retryAfterSeconds`, which then comes from the body and can be hours. Every API
-error also exposes the response `.headers`. 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.
+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.
## Receiving webhooks
diff --git a/sdk/javascript/src/errors.ts b/sdk/javascript/src/errors.ts
index 52baa073f..7d1de872b 100644
--- a/sdk/javascript/src/errors.ts
+++ b/sdk/javascript/src/errors.ts
@@ -111,10 +111,12 @@ export class OpenWANotImplementedError extends OpenWAApiError {}
*
* 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 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.
+ * 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.
*/
export class OpenWAServiceUnavailableError extends OpenWAApiError {}