Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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

Yudhi Armyndharis34c44dac457f
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index 3582d6928..81dcb2099 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -360,7 +360,7 @@ On a non-2xx response the SDK throws a typed `OpenWAApiError` subclass carrying
| Error class | HTTP status | Meaning |
| ------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OpenWAAuthError` | 401 | Missing or invalid API key. |
-| `OpenWAForbiddenError` | 403 | The key's role or scope refuses the call (e.g. an OPERATOR-only route, or a session, IP or chat outside the key's allow-lists). |
+| `OpenWAForbiddenError` | 403 | The key's role or scope refuses the call (e.g. an OPERATOR-only route, or a session, IP or chat outside the key's allow-lists), or WhatsApp itself refused the operation (for example, missing group admin rights). |
| `OpenWANotFoundError` | 404 | Resource not found. |
| `OpenWAConflictError` | 409 | Conflict — typically the engine is not ready. |
| `OpenWARateLimitError` | 429 | Rate limited. The global rate limiter's 429 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. |
@@ -732,7 +732,7 @@ Every error inherits from `OpenWAError`. A non-2xx response raises an `OpenWAApi
| Exception | Trigger |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OpenWAAuthError` | HTTP `401` — missing or invalid API key |
-| `OpenWAForbiddenError` | HTTP `403` — the key's role or scope (session, IP or chat allow-list) refuses the call |
+| `OpenWAForbiddenError` | HTTP `403` — the 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) |
| `OpenWANotFoundError` | HTTP `404` — resource not found |
| `OpenWAConflictError` | HTTP `409` — typically engine-not-ready |
| `OpenWARateLimitError` | HTTP `429` — too many requests. The global rate limiter's 429 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and `retry_after_seconds` carries its `Retry-After` header. A 429 whose `code` is `"SEND_PACING_LIMITED"` is not transient: do not retry it before `retry_after_seconds`, which then comes from the body and can be hours. |
@@ -1084,7 +1084,7 @@ All exceptions live in `OpenWA\Exceptions` and descend from `OpenWAException` (w
| `OpenWAException` | `\Exception` | Base for all SDK errors (also thrown for missing `baseUrl`/`apiKey`). |
| `OpenWAApiException` | `OpenWAException` | Any non-2xx (including unfollowed 3xx and other 4xx/5xx). |
| `OpenWAAuthException` | `OpenWAApiException` | `401` — missing/invalid API key. |
-| `OpenWAForbiddenException` | `OpenWAApiException` | `403` — the key's role or scope refuses the call (e.g. operator-only endpoint, or a session, IP or chat outside its allow-lists). |
+| `OpenWAForbiddenException` | `OpenWAApiException` | `403` — the key's role or scope refuses the call (e.g. operator-only endpoint, or a session, IP or chat outside its allow-lists), or WhatsApp itself refused the operation (for example, missing group admin rights). |
| `OpenWANotFoundException` | `OpenWAApiException` | `404` — resource not found. |
| `OpenWAConflictException` | `OpenWAApiException` | `409` — conflict (e.g. engine not ready). |
| `OpenWARateLimitException` | `OpenWAApiException` | `429` — rate limited. The global rate limiter's 429 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and `getRetryAfterSeconds()` carries its `Retry-After` header. A 429 whose `getErrorCode()` is `"SEND_PACING_LIMITED"` is not transient: do not retry it before `getRetryAfterSeconds()`, which then comes from the body and can be hours. |