Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(api): complete the 504 and template update rows

Yudhi Armyndharisec697ef3b384
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 69d326ea1..36bcc05c3 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -94,21 +94,21 @@ Validation failures (`statusCode: 400`) return `message` as an **array** of fiel
### General Error Codes
-| HTTP Status | Meaning | When |
-| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `400` | Bad Request | DTO validation failed, unknown body field, or a business precondition not met (e.g. session not active, media over cap) |
-| `401` | Unauthorized | Missing/invalid/expired/revoked `X-API-Key` (or `METRICS_TOKEN` for metrics), a blocked source IP, or a key used outside its `allowedSessions` scope |
-| `403` | Forbidden | A valid, in-scope key whose **role** is below the route's `@RequireRole` requirement |
-| `404` | Not Found | The addressed resource (session, message, webhook, batch, …) does not exist |
-| `409` | Conflict | A uniqueness constraint was violated (e.g. duplicate name); a credential teardown for the same session name is still in flight on `start`/`delete` (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`); or, on routes that reach a WhatsApp engine, the engine exists but is not ready yet (retryable; each route section carries the exact wording); or, on a multi-node deployment, another node currently owns the session's live engine (retryable) |
-| `413` | Payload Too Large | Base64 media exceeds the media byte cap (see §6.3) |
-| `415` | Unsupported Media | The request has a body carrying a `Content-Encoding` other than `identity`; compressed request bodies are not accepted, as the aggregate body cap counts wire bytes |
-| `429` | Too Many Requests | A rate limit was exceeded: the per-client-IP tiers, the ingress per-instance limit, or send pacing (body carries `code: 'SEND_PACING_LIMITED'` and `retryAfterSeconds`); honor `Retry-After` when present |
-| `500` | Internal Server Error | Send failed at the WhatsApp engine or an unexpected server error |
-| `501` | Not Implemented | The operation is not supported by the active engine (see the capability matrix, docs/29) |
-| `502` | Bad Gateway | An engine transport failure (e.g. a dead Baileys socket; retryable), an upstream component returned something unusable (not retryable; each route section carries the exact wording), or, on a multi-node deployment, forwarding a session-scoped request to its owner node failed after the request may already have been sent, so a non-idempotent call must not be replayed blindly (see docs/13) |
-| `503` | Service Unavailable | A dependency or the session is not ready (boot draining, a datastore down, the engine reconnecting); retryable. On a multi-node deployment a forwarded request answers `503` only when the owner node was never reached, so the request was not carried out (see docs/13) |
-| `504` | Gateway Timeout | An upstream the gateway waits on did not answer in time: on a multi-node deployment, the owner node did not answer a forwarded session-scoped request within `SESSION_PROXY_TIMEOUT_MS`; on `POST /sessions/{sessionId}/start`, a session pinned to an unreachable `proxyUrl` never connected (see §6.4.1). On the forwarding path the request may still have been carried out on the owner node, so a non-idempotent call must not be replayed blindly (see docs/13) |
+| HTTP Status | Meaning | When |
+| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` | Bad Request | DTO validation failed, unknown body field, or a business precondition not met (e.g. session not active, media over cap) |
+| `401` | Unauthorized | Missing/invalid/expired/revoked `X-API-Key` (or `METRICS_TOKEN` for metrics), a blocked source IP, or a key used outside its `allowedSessions` scope |
+| `403` | Forbidden | A valid, in-scope key whose **role** is below the route's `@RequireRole` requirement |
+| `404` | Not Found | The addressed resource (session, message, webhook, batch, …) does not exist |
+| `409` | Conflict | A uniqueness constraint was violated (e.g. duplicate name); a credential teardown for the same session name is still in flight on `start`/`delete` (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`); or, on routes that reach a WhatsApp engine, the engine exists but is not ready yet (retryable; each route section carries the exact wording); or, on a multi-node deployment, another node currently owns the session's live engine (retryable) |
+| `413` | Payload Too Large | Base64 media exceeds the media byte cap (see §6.3) |
+| `415` | Unsupported Media | The request has a body carrying a `Content-Encoding` other than `identity`; compressed request bodies are not accepted, as the aggregate body cap counts wire bytes |
+| `429` | Too Many Requests | A rate limit was exceeded: the per-client-IP tiers, the ingress per-instance limit, or send pacing (body carries `code: 'SEND_PACING_LIMITED'` and `retryAfterSeconds`); honor `Retry-After` when present |
+| `500` | Internal Server Error | Send failed at the WhatsApp engine or an unexpected server error |
+| `501` | Not Implemented | The operation is not supported by the active engine (see the capability matrix, docs/29) |
+| `502` | Bad Gateway | An engine transport failure (e.g. a dead Baileys socket; retryable), an upstream component returned something unusable (not retryable; each route section carries the exact wording), or, on a multi-node deployment, forwarding a session-scoped request to its owner node failed after the request may already have been sent, so a non-idempotent call must not be replayed blindly (see docs/13) |
+| `503` | Service Unavailable | A dependency or the session is not ready (boot draining, a datastore down, the engine reconnecting); retryable. On a multi-node deployment a forwarded request answers `503` only when the owner node was never reached, so the request was not carried out (see docs/13) |
+| `504` | Gateway Timeout | An upstream the gateway waits on did not answer in time: on a multi-node deployment, the owner node did not answer a forwarded session-scoped request within `SESSION_PROXY_TIMEOUT_MS`; on `POST /sessions/{sessionId}/start` (see §6.4.1), the engine did not finish starting within its timeout, either because the browser wedged mid-startup (often a container memory or resource limit) or because a session pinned to an unreachable `proxyUrl` never connected, and the message names which. On the forwarding path the request may still have been carried out on the owner node, so a non-idempotent call must not be replayed blindly (see docs/13) |
### Timestamp Conventions
@@ -613,7 +613,7 @@ No request body.
Returned via `transformSession`. Status typically transitions to `initializing` / `qr_ready`.
-**Errors:** `400` session already started / already starting · `401` · `403` · `404` not found · `409` credential teardown for the same session name still in flight (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`; no destructive side effect runs before the refusal — a retry after cleanup settles proceeds)
+**Errors:** `400` session already started / already starting · `401` · `403` · `404` not found · `409` credential teardown for the same session name still in flight (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`; no destructive side effect runs before the refusal — a retry after cleanup settles proceeds) · `504` the engine did not finish starting within its timeout (wedged browser, resource limit, or an unreachable `proxyUrl`); the engine is torn down, so the start can be retried once the cause is addressed
#### POST /api/sessions/:sessionId/stop
@@ -3373,12 +3373,12 @@ Update a template's name/body/header/footer (partial; only provided fields chang
**Request body** — `UpdateTemplateDto`
-| Field | Type | Required | Constraints | Description |
-| ------ | ------ | -------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| name | string | no | if present: non-empty, max 100 chars | Applied only when not `undefined`; explicit `null` → `400`. Duplicate name → `409`. |
-| body | string | no | if present: non-empty, max 4096 chars | Applied only when not `undefined`; explicit `null` → `400`. |
-| header | string | no | if present: max 1024 chars | Applied only when not `undefined`. Explicit `null` is accepted and **clears** the stored header (`200`); omit the key to leave it unchanged. |
-| footer | string | no | if present: max 1024 chars | Applied only when not `undefined`. Explicit `null` is accepted and **clears** the stored footer (`200`); omit the key to leave it unchanged. |
+| Field | Type | Required | Constraints | Description |
+| ------ | ------ | -------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| name | string | no | if present: non-empty, max 100 chars | Applied only when not `undefined`; explicit `null` → `400`. Duplicate name → `409`. |
+| body | string | no | if present: non-empty, max 4096 chars | Applied only when not `undefined`; explicit `null` → `400`. |
+| header | string | no | if present: max 1024 chars | Applied only when not `undefined`. Explicit `null` is accepted and **clears** the stored header (`200`); omit the key to leave it unchanged. The published schema types this field as a non-nullable `string`, so a generated or typed SDK client sends `""` instead, which the renderer skips exactly like `null`. |
+| footer | string | no | if present: max 1024 chars | Applied only when not `undefined`. Explicit `null` is accepted and **clears** the stored footer (`200`); omit the key to leave it unchanged. The published schema types this field as a non-nullable `string`, so a generated or typed SDK client sends `""` instead, which the renderer skips exactly like `null`. |
```json
{