Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
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.mdindex 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 & securitydiff --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 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.mdindex 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 expiresdefault), 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 webhooksdiff --git a/sdk/javascript/src/errors.ts b/sdk/javascript/src/errors.tsindex 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 {}