Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
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.mdindex 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. |