Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(sdk): stop reading a 503 as proof a forward never ran
Yudhi Armyndharis186eaecfc7b8
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex 81dcb2099..1aa59da1a 100644--- a/docs/18-sdk-design.md+++ b/docs/18-sdk-design.md@@ -357,17 +357,17 @@ Media bodies share the `SendMediaRequest` shape: `{ chatId, url? | base64?, mimeOn a non-2xx response the SDK throws a typed `OpenWAApiError` subclass carrying `.status` (HTTP status), `.body` (parsed JSON error envelope, or raw text), and `.errorKind` (the NestJS `error` field, `undefined` when the gateway omits it — which is the norm for a validation rejection in production, where `disableErrorMessages` is on). All error classes extend `OpenWAError` and are exported, so they are `instanceof`-checkable. A timeout throws `OpenWATimeoutError`, which extends `OpenWAError` directly (not `OpenWAApiError`). An API error also carries `.code` (the body's `code`, e.g. `SEND_PACING_LIMITED`), `.retryAfterSeconds` (the body's `retryAfterSeconds`, else the `Retry-After` header) and `.headers` (the response `Headers`).-| 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), 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. |-| `OpenWANotImplementedError` | 501 | The active engine does not support this operation. |-| `OpenWAServiceUnavailableError` | 503 | The engine did not confirm in time. Transient, though a catalog 503 can persist because WhatsApp may never answer that query; 501 is permanent. In a routed 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, which the owner may already have acted on. |-| `OpenWAApiError` | any other | Generic non-2xx (the base API error, e.g. `400`; also surfaced for unfollowed 3xx redirects). |-| `OpenWATimeoutError` | — | The request exceeded the configured timeout. |+| 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), 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. |+| `OpenWANotImplementedError` | 501 | The active engine does not support this operation. |+| `OpenWAServiceUnavailableError` | 503 | The engine did not confirm in time. Transient, though a catalog 503 can persist because WhatsApp may never answer that query; 501 is permanent. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on. |+| `OpenWAApiError` | any other | Generic non-2xx (the base API error, e.g. `400`; also surfaced for unfollowed 3xx redirects). |+| `OpenWATimeoutError` | — | The request exceeded the configured timeout. |```typescriptimport {@@ -729,17 +729,17 @@ Resources are accessed as properties on the client (e.g. `client.messages`). AllEvery error inherits from `OpenWAError`. A non-2xx response raises an `OpenWAApiError` (or a more specific subclass picked by status); a timeout raises `OpenWATimeoutError`. The API-error classes carry `.status` (HTTP code), `.body` (parsed JSON or raw text), and `.error_kind` (the NestJS `error` field), plus `.code` (the body's `code`), `.retry_after_seconds` (the body's `retryAfterSeconds`, else the `Retry-After` header) and `.headers` (the response headers).-| 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, 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. |-| `OpenWANotImplementedError` | HTTP `501` — active engine doesn't support the operation |-| `OpenWAServiceUnavailableError` | HTTP `503` — engine did not confirm in time; transient, though a catalog 503 can persist because WhatsApp may never answer that query. In a routed 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, which the owner may already have acted on |-| `OpenWAApiError` | any other non-2xx status (incl. unfollowed `3xx`) |-| `OpenWATimeoutError` | request exceeded `timeout` (has a `.timeout` attribute) |+| 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, 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. |+| `OpenWANotImplementedError` | HTTP `501` — active engine doesn't support the operation |+| `OpenWAServiceUnavailableError` | HTTP `503` — engine did not confirm in time; transient, though a catalog 503 can persist because WhatsApp may never answer that query. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on |+| `OpenWAApiError` | any other non-2xx status (incl. unfollowed `3xx`) |+| `OpenWATimeoutError` | request exceeded `timeout` (has a `.timeout` attribute) |```pythonfrom openwa import (@@ -1079,18 +1079,18 @@ All payloads are associative arrays; all listed methods are synchronous and retuAll exceptions live in `OpenWA\Exceptions` and descend from `OpenWAException` (which extends PHP's `\Exception`). Any non-2xx response is raised as an `OpenWAApiException`; the static `classify()` factory picks the most specific subclass by status code. An `OpenWAApiException` carries the HTTP status (`getStatus(): int`), the parsed error body (`getBody(): mixed`), and the NestJS `error` kind when present (`getErrorKind(): ?string`), plus the body's `code` (`getErrorCode(): ?string`), the retry delay in seconds from the body's `retryAfterSeconds` or the `Retry-After` header (`getRetryAfterSeconds(): ?int`) and the response headers (`getHeaders(): array`).-| Exception | Extends | Trigger |-| ----------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `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), 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. |-| `OpenWANotImplementedException` | `OpenWAApiException` | `501` — active engine does not support the operation. |-| `OpenWAServiceUnavailableException` | `OpenWAApiException` | `503` — engine did not confirm in time; transient, though a catalog 503 can persist because WhatsApp may never answer that query. In a routed 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, which the owner may already have acted on. |-| `OpenWATimeoutException` | `OpenWAException` | Request exceeded the timeout (`getTimeout(): float`). Not an API error — has no status/body. |+| Exception | Extends | Trigger |+| ----------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `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), 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. |+| `OpenWANotImplementedException` | `OpenWAApiException` | `501` — active engine does not support the operation. |+| `OpenWAServiceUnavailableException` | `OpenWAApiException` | `503` — engine did not confirm in time; transient, though a catalog 503 can persist because WhatsApp may never answer that query. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on. |+| `OpenWATimeoutException` | `OpenWAException` | Request exceeded the timeout (`getTimeout(): float`). Not an API error — has no status/body. |```php<?php