Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk-go): stop reading a 503 as proof a write never ran

Yudhi Armyndharis2079d8485fc7
diff --git a/sdk/go/README.md b/sdk/go/README.md
index 68a7355a0..8def58853 100644
--- a/sdk/go/README.md
+++ b/sdk/go/README.md
@@ -121,9 +121,12 @@ per-second tier, up to an hour for the hourly tier by default);
honors. A 429 whose `APIError.Code` is `"SEND_PACING_LIMITED"` is not transient:
do not retry it before `RetryAfter`, which then comes from the body and can be
hours. `APIError.Header` holds the response headers. 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.
+`*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
+that fails after the request reached it answers 502 or 504, and a 503 from the
+owner itself is relayed unchanged.
## Retries
diff --git a/sdk/go/errors.go b/sdk/go/errors.go
index 7e4a18536..d91eb52ae 100644
--- a/sdk/go/errors.go
+++ b/sdk/go/errors.go
@@ -47,10 +47,12 @@ var (
// 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.
+ // 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 in time, so a bounded write 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: 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")
)