Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): note that WhatsApp's own refusals also answer 403

Yudhi Armyndharisfc269df09424
diff --git a/sdk/java/README.md b/sdk/java/README.md
index 4e696af23..01af5fe43 100644
--- a/sdk/java/README.md
+++ b/sdk/java/README.md
@@ -113,17 +113,17 @@ try {
}
```
-| Class | HTTP | Meaning |
-| ------------------------------- | ---- | --------------------------------------- |
-| `OpenWAAuthError` | 401 | Missing or invalid API key |
-| `OpenWAForbiddenError` | 403 | API key role or scope refuses the call |
-| `OpenWANotFoundError` | 404 | Resource not found |
-| `OpenWAConflictError` | 409 | Engine not ready |
-| `OpenWARateLimitError` | 429 | Rate limited |
-| `OpenWANotImplementedError` | 501 | Active engine does not support the call |
-| `OpenWAServiceUnavailableError` | 503 | Engine did not confirm in time |
-| `OpenWAApiError` | — | Any other non-2xx (carries `.status()`) |
-| `OpenWATimeoutError` | — | Request exceeded the configured timeout |
+| Class | HTTP | Meaning |
+| ------------------------------- | ---- | ----------------------------------------------------------- |
+| `OpenWAAuthError` | 401 | Missing or invalid API key |
+| `OpenWAForbiddenError` | 403 | API key role or scope, or WhatsApp itself, refuses the call |
+| `OpenWANotFoundError` | 404 | Resource not found |
+| `OpenWAConflictError` | 409 | Engine not ready |
+| `OpenWARateLimitError` | 429 | Rate limited |
+| `OpenWANotImplementedError` | 501 | Active engine does not support the call |
+| `OpenWAServiceUnavailableError` | 503 | Engine did not confirm in time |
+| `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.
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWAForbiddenError.java b/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWAForbiddenError.java
index 852e2e0ad..5692ac001 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWAForbiddenError.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/errors/OpenWAForbiddenError.java
@@ -3,7 +3,10 @@ package com.rmyndharis.openwa.errors;
import java.util.List;
import java.util.Map;
-/** 403 Forbidden: the API key's role or scope (session, IP or chat allow-list) refuses the call. */
+/**
+ * 403 Forbidden: the API 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).
+ */
public class OpenWAForbiddenError extends OpenWAApiError {
public OpenWAForbiddenError(String message, int status, Object body, String errorKind) {
super(message, status, body, errorKind);
diff --git a/sdk/javascript/src/errors.ts b/sdk/javascript/src/errors.ts
index 4f625ce6e..52baa073f 100644
--- a/sdk/javascript/src/errors.ts
+++ b/sdk/javascript/src/errors.ts
@@ -83,7 +83,10 @@ export class OpenWAApiError extends OpenWAError {
/** 401 Unauthorized — missing or invalid API key. */
export class OpenWAAuthError extends OpenWAApiError {}
-/** 403 Forbidden: the API key's role or scope (session, IP or chat allow-list) refuses the call. */
+/**
+ * 403 Forbidden: the API 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).
+ */
export class OpenWAForbiddenError extends OpenWAApiError {}
/** 404 Not Found. */
export class OpenWANotFoundError extends OpenWAApiError {}