Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(sdk-go): never retry a send-pacing 429

Yudhi Armyndharisacb36300356d
diff --git a/sdk/README.md b/sdk/README.md
index b740af867..f11788914 100644
--- a/sdk/README.md
+++ b/sdk/README.md
@@ -241,7 +241,8 @@ testing, retry, tracing, or metrics. See [`go/README.md`](go/README.md).
the extension point for retry or observability middleware. The Go client is
the exception: it ships an opt-in policy (`WithRetry(DefaultRetryPolicy())`)
that retries idempotent requests on network errors and `429`/`5xx`, retries a
- `POST`/`PATCH` only on `429`/`503` (never after a network error), honors
+ `POST`/`PATCH` only on `429`/`503` (never after a network error), never
+ retries a send-pacing `429` (`code: "SEND_PACING_LIMITED"`), honors
`Retry-After`, and rewinds request bodies —
still off unless you ask for it.
- **Redirects are never followed.** A `3xx` surfaces to the caller rather than
diff --git a/sdk/go/README.md b/sdk/go/README.md
index 72c7ecdde..cdefd2f93 100644
--- a/sdk/go/README.md
+++ b/sdk/go/README.md
@@ -116,8 +116,10 @@ PUT, DELETE) are retried on network errors and on the policy's statuses (default
429/500/502/503/504). A POST or PATCH (every send endpoint is a POST) is never
retried after a network error and is retried only on 429 or 503 (when the policy
lists them): a 500/502/504 can arrive after the message was already sent, so
-replaying it could send it twice. Backoff is exponential, `Retry-After` is honored, and
-request bodies are safely rewound on each attempt.
+replaying it could send it twice. A 429 whose body has `code: "SEND_PACING_LIMITED"` is
+never retried, whatever the method: its delay is the body's `retryAfterSeconds`, which can be
+hours. Backoff is exponential, `Retry-After` is honored, and request bodies are safely rewound
+on each attempt.
```go
client, _ := openwa.New(baseURL, apiKey,
diff --git a/sdk/go/client_test.go b/sdk/go/client_test.go
index 6a4712d9b..8da716f06 100644
--- a/sdk/go/client_test.go
+++ b/sdk/go/client_test.go
@@ -346,6 +346,47 @@ func TestRetryReplaysPostOnBackpressure(t *testing.T) {
}
}
+// pacingTransport replies with the gateway's send-pacing refusal: a 429 with no
+// Retry-After whose body carries the real delay, which can be hours.
+type pacingTransport struct{ calls int32 }
+
+func (t *pacingTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+ atomic.AddInt32(&t.calls, 1)
+ if req.Body != nil {
+ _, _ = io.Copy(io.Discard, req.Body)
+ }
+ return &http.Response{
+ StatusCode: 429,
+ Body: io.NopCloser(strings.NewReader(
+ `{"statusCode":429,"message":"Daily send cap reached","code":"SEND_PACING_LIMITED","retryAfterSeconds":34521}`)),
+ Header: http.Header{},
+ Request: req,
+ }, nil
+}
+
+// A send-pacing refusal must not be retried before retryAfterSeconds, so the
+// policy returns it after one attempt, with the body intact for the caller.
+func TestRetryDoesNotReplaySendPacingRefusal(t *testing.T) {
+ rt := &pacingTransport{}
+ c := newTestClient(t, rt, WithRetry(RetryPolicy{
+ MaxRetries: 3, BaseDelay: time.Millisecond, MaxDelay: 5 * time.Millisecond,
+ RetryableStatuses: []int{429, 500, 502, 503, 504}, RespectRetryAfter: true,
+ }))
+
+ _, err := c.Messages.SendText(context.Background(), "s1", SendTextRequest{ChatID: "x", Text: "y"})
+ var apiErr *APIError
+ if !errors.As(err, &apiErr) || !errors.Is(err, ErrRateLimited) {
+ t.Fatalf("expected a 429 APIError, got %v", err)
+ }
+ if rt.calls != 1 {
+ t.Fatalf("a SEND_PACING_LIMITED 429 must not be retried: got %d attempts, want 1", rt.calls)
+ }
+ body, _ := apiErr.Body.(map[string]any)
+ if body["code"] != "SEND_PACING_LIMITED" || body["retryAfterSeconds"] != float64(34521) {
+ t.Fatalf("expected the refusal body to reach the caller, got %#v", apiErr.Body)
+ }
+}
+
func TestMiddlewarePipeline(t *testing.T) {
rt := &recordTransport{status: 200, body: `[]`}
var hits int32
diff --git a/sdk/go/retry.go b/sdk/go/retry.go
index 171fe924d..2d8c41b3f 100644
--- a/sdk/go/retry.go
+++ b/sdk/go/retry.go
@@ -1,7 +1,9 @@
package openwa
import (
+ "bytes"
"context"
+ "encoding/json"
"errors"
"io"
"net/http"
@@ -27,9 +29,12 @@ var idempotentMethods = map[string]bool{
// could double-send a WhatsApp message.
func isIdempotent(method string) bool { return idempotentMethods[method] }
-// backpressureStatuses are the statuses that mean the server declined the
-// request before acting on it: 429 (rate limited) and 503 (unavailable). Only
-// these are safe to retry for a non-idempotent method.
+// backpressureStatuses are the statuses a non-idempotent method may retry on:
+// 429 (rate limited) and 503 (unavailable), which usually mean the server
+// declined the request before acting on it. Not always: a 503 for a write
+// WhatsApp did not confirm in time can follow a write that was applied, so a
+// replayed POST may then report a conflict for a change that succeeded, and a
+// send-pacing 429 is never retried at all (see isSendPacingRefusal).
//
// The rest of the retryable set (500/502/504) can be returned AFTER the gateway
// has already sent the WhatsApp message — a 504 from a reverse proxy is the
@@ -58,10 +63,14 @@ func retryableForMethod(method string, status int) bool {
// Non-idempotent requests (POST — every send endpoint) are retried
// conservatively, because the SDK has no idempotency key to deduplicate with:
// never after a network error, and on a retryable status only for 429 and 503,
-// which prove the server declined the request before acting on it. A
+// which usually mean the server declined the request before acting on it. A
// 500/502/504 may arrive after the gateway already sent the message, so a POST
// is not replayed on those. Idempotent methods retry the full policy.
//
+// A 429 whose body carries code SEND_PACING_LIMITED is never retried, whatever
+// the method: it has no Retry-After, and its delay (body.retryAfterSeconds)
+// can be hours, so the refusal goes back to the caller at once.
+//
// Because every request the SDK issues sets req.GetBody, request bodies are
// safely rewound on each attempt.
type RetryPolicy struct {
@@ -148,6 +157,25 @@ func parseRetryAfter(resp *http.Response) (time.Duration, bool) {
return 0, false
}
+// isSendPacingRefusal reports whether resp is the gateway's send-pacing 429,
+// which must not be retried before the body's retryAfterSeconds. It reads the
+// body and puts the bytes back, so the caller still gets the full error.
+func isSendPacingRefusal(resp *http.Response) bool {
+ if resp.StatusCode != http.StatusTooManyRequests || resp.Body == nil {
+ return false
+ }
+ data, err := io.ReadAll(resp.Body)
+ _ = resp.Body.Close()
+ resp.Body = io.NopCloser(bytes.NewReader(data))
+ if err != nil {
+ return false
+ }
+ var body struct {
+ Code string `json:"code"`
+ }
+ return json.Unmarshal(data, &body) == nil && body.Code == "SEND_PACING_LIMITED"
+}
+
// retryMiddleware retries network errors and retryable statuses per policy,
// rewinding the body via req.GetBody and respecting context cancellation.
func retryMiddleware(p RetryPolicy, log Logger) Middleware {
@@ -179,11 +207,13 @@ func retryMiddleware(p RetryPolicy, log Logger) Middleware {
retryable = isIdempotent(req.Method)
case resp != nil && p.retryableStatus(resp.StatusCode):
// A retryable HTTP status is the server explicitly telling
- // us to back off — but only 429/503 prove it declined the
- // request before acting on it. A 500/502/504 can arrive
+ // us to back off, but only 429/503 usually mean it declined
+ // the request before acting on it. A 500/502/504 can arrive
// after the gateway already sent the message, so replaying
- // a POST on those would double-send.
- retryable = retryableForMethod(req.Method, resp.StatusCode)
+ // a POST on those would double-send. A send-pacing 429 is
+ // not transient, so it goes back to the caller.
+ retryable = retryableForMethod(req.Method, resp.StatusCode) &&
+ attempt < p.MaxRetries && !isSendPacingRefusal(resp)
}
if !retryable || attempt >= p.MaxRetries {
return resp, err