Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(session): narrow the delete case of the start 409

Yudhi Armyndharisedef66a4926b
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 3f934e6ea..f21abfe5b 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -663,7 +663,7 @@ Returned via `transformSession`. Status typically transitions to `initializing`
A session stopped with `POST /stop` or `POST /force-kill` is marked to run again only once the start gets past the `400` and `409` refusals below; a refused start leaves the stop in place.
-**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), or, with no `code`, a `POST /stop` or `POST /force-kill` of this session that finished while the start was waiting (the stop stands; a new `POST /start` clears it and starts the session) · `504` the engine did not finish starting within its timeout (WhatsApp Web or the network unreachable, a stalled browser or resource limit, or, on whatsapp-web.js, an unreachable `proxyUrl`); the engine is torn down, so the start can be retried once the cause is addressed
+**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), or, with no `code`, a `POST /stop`, `POST /force-kill` or data import (`stopOrphans`) of this session that began or finished while the start was waiting, or a delete of it still running (the start yields and launches nothing; after a stop or force-kill a new `POST /start` clears it and starts the session, after a delete or an import that removed the session the retry answers `404`) · `504` the engine did not finish starting within its timeout (WhatsApp Web or the network unreachable, a stalled browser or resource limit, or, on whatsapp-web.js, an unreachable `proxyUrl`); the engine is torn down, so the start can be retried once the cause is addressed
#### POST /api/sessions/:sessionId/stop
diff --git a/openapi.json b/openapi.json
index 8ab73c7bf..62c4f86d9 100644
--- a/openapi.json
+++ b/openapi.json
@@ -1268,7 +1268,7 @@
}
},
"409": {
- "description": "A credential teardown for the same session name is still in flight (e.g. a prior logout that owns destructive cleanup). Retryable — the body carries `code: SESSION_NAME_TEARDOWN_PENDING`; wait for it to settle and retry. No destructive side effect runs before this refusal. Also returned when another node currently holds this session's engine: only the owner may start it, and the claim is refused before any engine is launched, so no second connection to the account is opened. Also returned, with no `code`, when a stop or force-kill of this session finished while the start was waiting: the stop stands, and a new POST /start clears it and starts the session.",
+ "description": "A credential teardown for the same session name is still in flight (e.g. a prior logout that owns destructive cleanup). Retryable — the body carries `code: SESSION_NAME_TEARDOWN_PENDING`; wait for it to settle and retry. No destructive side effect runs before this refusal. Also returned when another node currently holds this session's engine: only the owner may start it, and the claim is refused before any engine is launched, so no second connection to the account is opened. Also returned, with no `code`, when a stop, force-kill or data import (`stopOrphans`) of this session began or finished while the start was waiting, or a delete of it was still running: the start yields and launches nothing. After a stop or force-kill, a new POST /start clears it and starts the session; after a delete, or an import that removed the session, the retry answers 404.",
"content": {
"application/json": {
"schema": {
@@ -13013,7 +13013,7 @@
}
},
"404": {
- "description": "No such channel — the id is not among the session's subscribed channels, either because it is wrong or because the channel has not synced into the local collection yet.",
+ "description": "The id is not a channel id (it does not end in `@newsletter`). Retrying the same id cannot succeed.",
"content": {
"application/json": {
"schema": {
@@ -13228,7 +13228,7 @@
}
},
"404": {
- "description": "No such channel — the id is not among the session's subscribed channels, either because it is wrong or because the channel has not synced into the local collection yet.",
+ "description": "The id is not a channel id (it does not end in `@newsletter`). Retrying the same id cannot succeed.",
"content": {
"application/json": {
"schema": {
diff --git a/src/modules/session/session.controller.ts b/src/modules/session/session.controller.ts
index c325cd826..9cb6ff578 100644
--- a/src/modules/session/session.controller.ts
+++ b/src/modules/session/session.controller.ts
@@ -313,10 +313,10 @@ export class SessionController {
'effect runs before this refusal. Also returned when another node currently holds this ' +
"session's engine: only the owner may start it, and the claim is refused before any engine " +
'is launched, so no second connection to the account is opened. Also returned, with no `code`, ' +
- 'when a stop, force-kill, delete or data import (`stopOrphans`) of this session began or ' +
- 'finished while the start was waiting: the start yields and launches nothing. After a stop or ' +
- 'force-kill, a new POST /start clears it and starts the session; after a delete, or an import ' +
- 'that removed the session, the retry answers 404.',
+ 'when a stop, force-kill or data import (`stopOrphans`) of this session began or finished ' +
+ 'while the start was waiting, or a delete of it was still running: the start yields and launches ' +
+ 'nothing. After a stop or force-kill, a new POST /start clears it and starts the session; after ' +
+ 'a delete, or an import that removed the session, the retry answers 404.',
})
@ApiResponse({
status: 504,