Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): document the incomplete force-kill 502

Yudhi Armyndharisb918fd20ddd0
diff --git a/sdk/go/sessions.go b/sdk/go/sessions.go
index 253833837..5afff7322 100644
--- a/sdk/go/sessions.go
+++ b/sdk/go/sessions.go
@@ -125,7 +125,12 @@ func (s *SessionsService) Logout(ctx context.Context, sessionID string) (*Sessio
return &out, nil
}
-// ForceKill terminates a stuck session immediately.
+// ForceKill terminates a stuck session immediately. It returns an *APIError with
+// StatusCode 502 and Code "SESSION_FORCE_KILL_INCOMPLETE" when the session was
+// stopped locally but the force-destroy threw or timed out, so the engine process
+// may still be running; the status is settled to disconnected and a retry
+// answers 400 because no engine is left to kill. Restart the node to reap a
+// leaked process.
func (s *SessionsService) ForceKill(ctx context.Context, sessionID string) (*SessionResponse, error) {
var out SessionResponse
err := s.client.do(ctx, "POST", "/api/sessions/"+pathEscape(sessionID)+"/force-kill", nil, nil, &out)
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/resources/SessionsResource.java b/sdk/java/src/main/java/com/rmyndharis/openwa/resources/SessionsResource.java
index 9bd3b4d36..f49bf5656 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/resources/SessionsResource.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/resources/SessionsResource.java
@@ -117,7 +117,13 @@ public final class SessionsResource {
return client.request(HttpMethod.POST, "/api/sessions/" + encodeSegment(id) + "/logout", null, null, SessionResponse.class);
}
- /** Force-kill a stuck session (SIGKILL + teardown). */
+ /**
+ * Force-kill a stuck session (SIGKILL + teardown). Throws with HTTP 502 and {@code code()}
+ * {@code SESSION_FORCE_KILL_INCOMPLETE} when the session was stopped locally but the
+ * force-destroy threw or timed out, so the engine process may still be running; the status is
+ * settled to {@code disconnected} and a retry answers 400 because no engine is left to kill.
+ * Restart the node to reap a leaked process.
+ */
public SessionResponse forceKill(String id) {
return client.request(HttpMethod.POST, "/api/sessions/" + encodeSegment(id) + "/force-kill", null, null, SessionResponse.class);
}
diff --git a/sdk/php/src/Resources/SessionsResource.php b/sdk/php/src/Resources/SessionsResource.php
index 841048b0b..f9067406e 100644
--- a/sdk/php/src/Resources/SessionsResource.php
+++ b/sdk/php/src/Resources/SessionsResource.php
@@ -143,7 +143,15 @@ class SessionsResource
return $this->http->request('POST', "/api/sessions/{$this->http->encodeSegment($id)}/logout");
}
- /** @return array<string,mixed> */
+ /**
+ * Force-kill a stuck session (SIGKILL + teardown). Throws with HTTP 502 and
+ * getErrorCode() 'SESSION_FORCE_KILL_INCOMPLETE' when the session was stopped
+ * locally but the force-destroy threw or timed out, so the engine process may
+ * still be running; the status is settled to disconnected and a retry answers 400
+ * because no engine is left to kill. Restart the node to reap a leaked process.
+ *
+ * @return array<string,mixed>
+ */
public function forceKill(string $id): array
{
return $this->http->request('POST', "/api/sessions/{$this->http->encodeSegment($id)}/force-kill");
diff --git a/sdk/python/openwa/resources/sessions.py b/sdk/python/openwa/resources/sessions.py
index 26f0f99a9..2ac799be7 100644
--- a/sdk/python/openwa/resources/sessions.py
+++ b/sdk/python/openwa/resources/sessions.py
@@ -120,7 +120,13 @@ class SessionsResource:
return self._http.request("POST", f"/api/sessions/{quote_segment(session_id)}/logout")
def force_kill(self, session_id: str) -> SessionResponse:
- """Terminate a stuck session immediately."""
+ """Terminate a stuck session immediately.
+
+ Raises with HTTP 502 and ``code`` ``SESSION_FORCE_KILL_INCOMPLETE`` when the session was
+ stopped locally but the force-destroy threw or timed out, so the engine process may still be
+ running; the status is settled to disconnected and a retry answers 400 because no engine is
+ left to kill. Restart the node to reap a leaked process.
+ """
return self._http.request("POST", f"/api/sessions/{quote_segment(session_id)}/force-kill")
def get_qr_code(self, session_id: str) -> QrCodeResponse: