Close Session

Endpoint

Authentication

All requests to the BBRE API require authentication via an API key. You must include your API key in the HTTP headers of every request, including session close operations. The API accepts the key through either the x-api-key header or the apikey header. Both header names are supported and functionally identical. The API key used to close a session must belong to the same account that created the session. You cannot close sessions that belong to other accounts. If no API key is provided, the API returns a 401 error with the API_KEY_REQUIRED error code. If the provided key is invalid or belongs to a suspended or inactive account, the API returns a 403 error with the appropriate error code (INVALID_API_KEY, ACCOUNT_SUSPENDED, or ACCOUNT_INACTIVE).

Request Body Parameters

The request body must be a JSON object containing the session ID of the session you want to close. The sessionId parameter is the only parameter accepted by this endpoint and it is required. The session ID is the unique identifier that was returned when you created the session using the POST /session/create endpoint. If you do not provide a session ID, the request validator returns a 400 SESSION_ID_REQUIRED error before the request reaches the controller. The session ID format is a string that typically starts with session_ followed by an alphanumeric identifier, but you should treat it as an opaque string and always use the exact value returned by the session creation endpoint.

When to Close Sessions

Knowing when to close a session is just as important as knowing how to close one. The general rule is simple: close a session as soon as you no longer need it. However, there are several specific scenarios where session closure is the correct action, and understanding these scenarios helps you build more robust and resource-efficient integrations.

1. Workflow Completion

The most common scenario for closing a session is when your multi-step workflow has finished successfully. For example, after you have logged into a website, navigated to the target page, extracted the data you need, and stored it in your database, the session has served its purpose and should be closed immediately. There is no benefit to keeping the session alive after the workflow is complete, and doing so wastes one of your 10 active session slots. Always place the close call at the end of your workflow logic, ideally inside a finally block to ensure it executes regardless of whether the workflow succeeded or failed.

2. Error Recovery

When your workflow encounters an unrecoverable error, such as the target website returning an unexpected response, a critical page being unavailable, or your application logic detecting that the workflow cannot proceed, you should close the session before handling the error. This prevents orphaned sessions from accumulating and consuming your session slots. Even if you plan to retry the workflow, it is better to close the current session and create a fresh one for the retry attempt, because the existing session may have accumulated state (cookies, navigation history) that contributed to the failure.

3. Session Slot Management

If your application needs to create a new session but you are approaching or have reached the 10-session limit, you should close the oldest or least-needed active session to free up a slot. Use the POST /account/sessions endpoint to list your active sessions and identify candidates for closure. Sessions that have been idle for a long time or that belong to completed workflows are the best candidates. Implementing a session pool pattern where you proactively manage session lifecycle prevents the SESSION_LIMIT_REACHED error from disrupting your application flow.

4. Application Shutdown

When your application is shutting down (whether gracefully or due to a crash), you should close all active sessions as part of the shutdown procedure. Register a shutdown handler (such as listening for SIGTERM or SIGINT signals in Node.js, or using atexit in Python) that iterates through your tracked session IDs and closes each one. This ensures that server resources are released promptly and your session slots are freed for the next time your application starts. If your application crashes without closing sessions, those sessions will remain active until their timeout expires.

Request Examples

The following examples demonstrate how to close a BBRE session in different programming languages and for different use cases. All examples show complete, working code that you can copy and run directly. Remember to replace YOUR_API_KEY with your actual BBRE API key and session_abc123def456 with the session ID returned by the session creation endpoint.

Basic Session Close

The simplest way to close a session. This sends the session ID to the close endpoint and logs the result. Use this pattern when you have a single session to close at the end of your workflow.

const axios = require("axios");

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";

async function closeSession(sessionId) {
  const response = await axios.post(
    API_BASE + "/session/close",
    { sessionId: sessionId },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      }
    }
  );

  console.log("Session closed:", response.data.data.session.id);
  console.log("Status:", response.data.data.session.status);

  return response.data;
}

closeSession("session_abc123def456");

import requests

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

response = requests.post(
    API_BASE + "/session/close",
    headers=headers,
    json={"sessionId": "session_abc123def456"}
)

data = response.json()
session = data["data"]["session"]
print("Session closed:", session["id"])
print("Status:", session["status"])

curl -X POST https://bbre-solver-api.mydisct.com/session/close \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"sessionId": "session_abc123def456"}'

Safe Session Close with Error Handling

In production applications, you should always wrap the session close call in error handling logic. The close operation can fail if the session has already been closed, if the session does not exist, or if there is a temporary server error. The following examples demonstrate a robust close pattern that handles all possible error scenarios gracefully and logs appropriate messages for debugging.

const axios = require("axios");

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";
const authHeaders = {
  "Content-Type": "application/json",
  "x-api-key": API_KEY
};

async function safeCloseSession(sessionId) {
  try {
    const response = await axios.post(
      API_BASE + "/session/close",
      { sessionId: sessionId },
      { headers: authHeaders }
    );
    console.log("Session", sessionId, "closed successfully");
    return { success: true, data: response.data };
  } catch (error) {
    if (error.response) {
      const errorCode = error.response.data.error?.code;
      if (errorCode === "SESSION_CLOSED") {
        console.log("Session", sessionId, "was already closed");
        return { success: true, alreadyClosed: true };
      }
      if (errorCode === "SESSION_NOT_FOUND") {
        console.log("Session", sessionId, "not found, may have expired");
        return { success: true, notFound: true };
      }
      console.error("Failed to close session:", errorCode);
      return { success: false, error: errorCode };
    }
    console.error("Network error closing session:", error.message);
    return { success: false, error: "NETWORK_ERROR" };
  }
}

safeCloseSession("session_abc123def456");

import requests

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

def safe_close_session(session_id):
    try:
        response = requests.post(
            API_BASE + "/session/close",
            headers=headers,
            json={"sessionId": session_id}
        )

        if response.status_code == 200:
            print(f"Session {session_id} closed successfully")
            return {"success": True, "data": response.json()}

        error_data = response.json()
        error_code = error_data.get("error", {}).get("code", "UNKNOWN")

        if error_code == "SESSION_CLOSED":
            print(f"Session {session_id} was already closed")
            return {"success": True, "already_closed": True}

        if error_code == "SESSION_NOT_FOUND":
            print(f"Session {session_id} not found, may have expired")
            return {"success": True, "not_found": True}

        print(f"Failed to close session: {error_code}")
        return {"success": False, "error": error_code}

    except requests.exceptions.RequestException as e:
        print(f"Network error closing session: {e}")
        return {"success": False, "error": "NETWORK_ERROR"}

safe_close_session("session_abc123def456")

Complete Workflow with Session Close

The following example demonstrates the recommended pattern for using sessions: create a session, perform your workflow, and always close the session in a finally block. This ensures the session is closed regardless of whether the workflow succeeds or encounters an error. This pattern is the foundation of reliable BBRE session management and should be used in every production integration.

const axios = require("axios");

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";
const authHeaders = {
  "Content-Type": "application/json",
  "x-api-key": API_KEY
};

async function scrapeWithSession() {
  let sessionId = null;

  try {
    const createResponse = await axios.post(
      API_BASE + "/session/create",
      { mode: "passive", sensibility: "medium", timeout: 300 },
      { headers: authHeaders }
    );
    sessionId = createResponse.data.session.id;
    console.log("Session created:", sessionId);

    const loginResponse = await axios.post(
      API_BASE + "/session/request",
      {
        sessionId: sessionId,
        url: "https://example.com/api/login",
        method: "POST",
        body: { username: "myuser", password: "mypassword" }
      },
      { headers: authHeaders }
    );
    console.log("Login status:", loginResponse.data.data.task.result.statusCode);

    const dataResponse = await axios.post(
      API_BASE + "/session/request",
      {
        sessionId: sessionId,
        url: "https://example.com/api/data",
        method: "GET"
      },
      { headers: authHeaders }
    );
    console.log("Data fetched:", dataResponse.data.data.task.result.statusCode);

    return dataResponse.data.data.task.result.body;

  } finally {
    if (sessionId) {
      await axios.post(
        API_BASE + "/session/close",
        { sessionId: sessionId },
        { headers: authHeaders }
      ).catch(err => console.error("Failed to close session:", err.message));
      console.log("Session closed:", sessionId);
    }
  }
}

scrapeWithSession();

import requests

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

session_id = None

try:
    create_response = requests.post(
        API_BASE + "/session/create",
        headers=headers,
        json={"mode": "passive", "sensibility": "medium", "timeout": 300}
    )
    session_id = create_response.json()["session"]["id"]
    print("Session created:", session_id)

    login_response = requests.post(
        API_BASE + "/session/request",
        headers=headers,
        json={
            "sessionId": session_id,
            "url": "https://example.com/api/login",
            "method": "POST",
            "body": {"username": "myuser", "password": "mypassword"}
        }
    )
    print("Login status:", login_response.json()["data"]["task"]["result"]["statusCode"])

    data_response = requests.post(
        API_BASE + "/session/request",
        headers=headers,
        json={
            "sessionId": session_id,
            "url": "https://example.com/api/data",
            "method": "GET"
        }
    )
    print("Data fetched:", data_response.json()["data"]["task"]["result"]["statusCode"])

finally:
    if session_id:
        try:
            requests.post(
                API_BASE + "/session/close",
                headers=headers,
                json={"sessionId": session_id}
            )
            print("Session closed:", session_id)
        except Exception as e:
            print("Failed to close session:", e)

SESSION_RESPONSE=$(curl -s -X POST https://bbre-solver-api.mydisct.com/session/create \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"mode": "passive", "timeout": 300}')

SESSION_ID=$(echo $SESSION_RESPONSE | jq -r '.session.id')
echo "Session created: $SESSION_ID"

curl -s -X POST https://bbre-solver-api.mydisct.com/session/request \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d "{\"sessionId\": \"$SESSION_ID\", \"url\": \"https://example.com/api/data\", \"method\": \"GET\"}"

curl -s -X POST https://bbre-solver-api.mydisct.com/session/close \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d "{\"sessionId\": \"$SESSION_ID\"}"

echo "Session closed: $SESSION_ID"

Response Format

The session close endpoint returns a JSON response indicating whether the session was closed successfully. On success, the response includes the session ID and its updated status. On failure, the response includes an error code, a human-readable message, and additional details where applicable. The response always includes the "service": "MyDisct Solver BBRE" field to identify which service processed the request.

Success Response (200)

A successful session close returns the following structure. The session.id confirms which session was closed, and the session.status is always "closed" in a successful response. Once a session is closed, it cannot be reopened or reused. You must create a new session if you need to continue interacting with the target website.

{
  "success": true,
  "service": "MyDisct Solver BBRE",
  "data": {
    "session": {
      "id": "session_abc123def456",
      "status": "closed"
    }
  }
}

Error Response Examples

When the session close operation fails, the API returns an error response with the appropriate HTTP status code, error code, and a descriptive message. The following examples show the most common error responses you may encounter when closing sessions.

400 - Session Already Closed

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "SESSION_CLOSED",
    "message": "Session is already closed."
  }
}

400 - Session ID Required

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "SESSION_ID_REQUIRED",
    "message": "Session ID is required.",
    "details": {
      "hint": "Session ID is returned when you create a session"
    }
  }
}

404 - Session Not Found

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "Session not found."
  }
}

Error Codes

The following table lists all error codes that can be returned by the session close endpoint, along with their HTTP status codes, descriptions, and recommended solutions. Implementing proper error handling for each of these codes ensures your application can recover gracefully from any failure scenario. Note that some error codes like SESSION_CLOSED and SESSION_NOT_FOUND are not necessarily fatal errors in the context of session cleanup. If you are closing a session as part of cleanup logic, you can safely treat these as successful outcomes since the end result is the same: the session is no longer active and is not consuming your session slots.

Node.js SDK Usage

The mydisctsolver-bbre Node.js SDK provides two convenient ways to close sessions. The BBREClient class has a closeSession() method that accepts a session ID and closes the session directly. Additionally, if you are using the BBRESession class for session-based workflows, the session object itself has a close() method that closes the session it represents. Both methods wrap the POST /session/close endpoint and handle authentication headers, request formatting, and response parsing automatically.

Close Session via BBREClient

Use the client.closeSession() method when you have a session ID stored as a string and want to close it directly through the client instance. This is useful when you are managing session IDs manually or when you need to close a session from a different part of your application than where it was created.

const BBREClient = require("mydisctsolver-bbre");

const client = new BBREClient({
  apiKey: "YOUR_API_KEY"
});

async function closeWithClient() {
  const sessionId = "session_abc123def456";

  const result = await client.closeSession(sessionId);
  console.log("Session closed:", result.session.id);
  console.log("Status:", result.session.status);

  return result;
}

closeWithClient();

Close Session via BBRESession Object

When you create a session using the SDK's session management features, the returned BBRESession object has a built-in close() method. This is the most natural way to close sessions in SDK-based workflows because the session object already knows its own session ID and the client configuration needed to make the API call.

const BBREClient = require("mydisctsolver-bbre");

const client = new BBREClient({
  apiKey: "YOUR_API_KEY",
  mode: "passive",
  sensibility: "medium"
});

async function workflowWithSessionClose() {
  const session = await client.createSession({ timeout: 300 });
  console.log("Session created:", session.sessionId);

  try {
    const loginResult = await session.request({
      url: "https://example.com/api/login",
      method: "POST",
      body: { username: "myuser", password: "mypassword" }
    });
    console.log("Login status:", loginResult.statusCode);

    const dataResult = await session.request({
      url: "https://example.com/api/data",
      method: "GET"
    });
    console.log("Data fetched:", dataResult.statusCode);

    return dataResult.body;

  } finally {
    await session.close();
    console.log("Session closed");
  }
}

workflowWithSessionClose();

Batch Close Multiple Sessions

If your application manages multiple sessions simultaneously, you may need to close several sessions at once during cleanup. The following example demonstrates how to close multiple sessions in parallel using Promise.allSettled(), which ensures all close attempts complete even if some fail. This is particularly useful during application shutdown or when implementing a session pool reset.

const BBREClient = require("mydisctsolver-bbre");

const client = new BBREClient({
  apiKey: "YOUR_API_KEY"
});

async function closeAllSessions(sessionIds) {
  const closePromises = sessionIds.map(id =>
    client.closeSession(id)
      .then(() => ({ id, status: "closed" }))
      .catch(err => ({ id, status: "failed", error: err.message }))
  );

  const results = await Promise.allSettled(closePromises);

  results.forEach(result => {
    if (result.status === "fulfilled") {
      const data = result.value;
      console.log("Session", data.id, ":", data.status);
    }
  });

  return results;
}

const activeSessions = [
  "session_abc123",
  "session_def456",
  "session_ghi789"
];

closeAllSessions(activeSessions);

The SDK methods throw an error if the API returns an error response. For cleanup scenarios, wrap the close call in a try/catch block and treat SESSION_CLOSED and SESSION_NOT_FOUND errors as non-fatal conditions. For more details on the SDK session management methods, see the Session Management documentation.

Best Practices

Common Issues

Issue 1: SESSION_CLOSED Error When Closing a Session

Solution: This error is not a problem in most cases. It simply means the session was already closed before your close request arrived. In your error handling logic, check for the SESSION_CLOSED error code and treat it as a successful outcome. The session is no longer active and is not consuming your session slots, which is the desired result. If you want to prevent this error entirely, you can track session state locally in your application and skip the close call if you have already recorded a successful close for that session ID. However, the simpler approach is to always attempt the close and handle the SESSION_CLOSED response gracefully.

Issue 2: SESSION_NOT_FOUND When Closing a Session

Solution: There are three common causes for this error. First, the session ID might be incorrect due to a typo or a variable assignment error in your code. Double-check that the session ID you are sending matches exactly the value returned by POST /session/create. Second, you might be using a different API key than the one used to create the session. Sessions are scoped to the account that created them, so you must use the same API key for both creation and closure. Third, the session record may have been removed from the system after expiration. In cleanup scenarios, treat SESSION_NOT_FOUND as a non-fatal condition since the session is not consuming your session slots regardless of the reason it was not found.

Issue 3: Leaked Sessions Causing SESSION_LIMIT_REACHED

Solution: Session leaks are almost always caused by missing close calls in error paths. Review your code and ensure every code path that creates a session also closes it, including error handling paths. The most reliable fix is to use the try/finally pattern described in the Best Practices section above. Additionally, use the POST /account/sessions endpoint to list your currently active sessions and close any that are no longer needed. As a temporary workaround, you can close leaked sessions manually using this endpoint with each session ID. For a permanent fix, audit your codebase and wrap every session creation in a try/finally block that guarantees the session is closed when the workflow ends.

Related Documentation

• Create Session - Learn how to create BBRE sessions with custom mode, sensibility, fingerprint, proxy, and timeout configuration
• Session Status - Check the current status, request count, total charged amount, and expiration time of an active session before deciding whether to close it
• Session Request - Send HTTP requests within an active session to maintain cookies, fingerprint, and browser state across multiple interactions
• Account Sessions - List all your sessions with filtering options to identify active sessions that can be closed to free up session slots
• BBRE Engine Overview - Understand the BBRE architecture, session lifecycle, passive and adaptive modes, and core concepts
• SDK Session Management - Detailed documentation for the Node.js SDK session management methods including createSession, closeSession, and getSessionStatus