Chat with us, powered by LiveChat
← Return to MyDisct Solver

Execute Synchronous Request

The POST /request/execute endpoint provides a synchronous interface to the BBRE (Browser-Backed Request Engine) system. Unlike the asynchronous POST /request/create endpoint where you submit a task and poll for the result separately, the execute endpoint combines both steps into a single HTTP call. You send your request parameters, the BBRE engine processes the request in real time, and the complete result is returned directly in the HTTP response. There is no task ID to track and no polling loop to implement. This makes the synchronous endpoint significantly simpler to integrate, especially for scripts, prototyping, and applications where you need the result immediately before proceeding. The trade-off is that your HTTP connection stays open for the entire duration of processing, which can range from a few seconds for passive mode requests to over a minute for complex adaptive mode requests on heavily protected sites. The POST /request/sync endpoint is a complete alias for /request/execute. Both endpoints use the same controller, accept the same parameters, and return the same response format. You can use whichever URL feels more natural in your codebase. This page covers the full parameter reference, working code examples in JavaScript, Python, and cURL, the synchronous response format, timeout management strategies, a detailed comparison between synchronous and asynchronous approaches, error handling patterns, and SDK integration for synchronous requests.

Synchronous vs Asynchronous

This endpoint waits for the BBRE engine to finish processing before returning the response. Your HTTP connection remains open until the result is ready or the timeout is reached. The default timeout for synchronous requests is 120 seconds, which is higher than the 30-second default for asynchronous requests created via POST /request/create. If you need to process many requests concurrently or want more control over timeout handling, consider using the asynchronous workflow instead. For single requests, quick scripts, and prototyping, the synchronous endpoint is the fastest way to get results.

Endpoints

Both endpoints below are functionally identical. The /request/sync path is an alias that maps to the same internal handler as /request/execute. They accept the same request body, use the same validation pipeline, and return the same response structure. Choose whichever URL reads better in your application code.

POST https://bbre-solver-api.mydisct.com/request/execute
POST https://bbre-solver-api.mydisct.com/request/sync

Authentication

Every request to the BBRE API must include a valid API key in the HTTP headers. The API accepts the key through either the x-api-key header or the apikey header. Both header names are supported and functionally identical. 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 account, the API returns a 403 error with the appropriate error code (INVALID_API_KEY, ACCOUNT_SUSPENDED, or ACCOUNT_INACTIVE).

Header Type Required Description
x-api-key string required Your BBRE API key. You can find this in your MyDisct Solver dashboard.
Content-Type string required Must be set to application/json for all requests.

Request Body Parameters

The request body is a JSON object containing the parameters for your HTTP request. The parameter set is identical to the POST /request/create endpoint with one important difference: the default timeout value is 120 seconds instead of 30 seconds. This higher default accounts for the fact that synchronous requests hold the connection open for the entire processing duration, and complex pages processed in adaptive mode with high sensibility can take significant time to complete. The only required parameter is url. All other parameters are optional and have sensible defaults.

Parameter Type Required Default Description
url string required - The target URL to request. Must be a valid, fully qualified URL including the protocol (http:// or https://). This is the only required parameter. Example: https://example.com/api/data
method string optional "GET" The HTTP method to use for the request. Supported values: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS. Case-insensitive.
headers object optional {} Custom HTTP headers to include in the request. Provided as key-value pairs. BBRE automatically adds standard browser headers (User-Agent, Accept, etc.) based on the fingerprint, so you only need to add headers specific to your use case.
body string / object optional null The request body to send. Used primarily with POST, PUT, and PATCH methods. Can be a JSON object (serialized automatically) or a string (sent as-is).
params object optional null URL query parameters to append to the URL. Provided as key-value pairs. These are URL-encoded and appended automatically. Example: {"page": "1", "limit": "50"}
mode string optional "passive" The request processing mode. "passive" sends the request through a browser-like HTTP client with realistic headers and fingerprinting but without full browser rendering. "adaptive" launches a full browser instance, renders the page, executes JavaScript, and handles dynamic content. Use passive for simple HTTP requests and adaptive when the target site requires JavaScript execution or has advanced bot detection.
sensibility string optional "medium" The detection evasion sensitivity level. "low" provides basic evasion with faster processing. "medium" balances evasion quality and speed. "high" applies maximum evasion techniques including human-like timing delays, realistic mouse movements, and advanced fingerprint consistency checks.
fingerprint object optional {} Custom browser fingerprint configuration. Allows you to specify userAgent, platform, screen (object with width and height), timezone, language, and webgl (object with vendor and renderer). Unspecified attributes are generated automatically. See the Fingerprint and Profile Guide.
proxy object optional null Proxy server configuration. The object should contain host (string, required), port (number, required), and optionally username and password for authenticated proxies.
cookies object optional {} Cookies to include in the request as key-value pairs. These cookies are sent as if they were set by the browser. Useful for maintaining session state or passing authentication tokens.
timeout number optional 120 Request timeout in seconds. The maximum time BBRE will spend processing the request before returning a timeout error. Valid range is 1 to 300 seconds. The default for synchronous requests is 120 seconds, which is higher than the 30-second default for asynchronous requests. For passive mode, 30-60 seconds is usually sufficient. For adaptive mode with complex pages, 120 seconds or more may be needed.
allowRedirects boolean optional true Whether to follow HTTP redirects (301, 302, 303, 307, 308). When false, the redirect response itself is returned without following it.
maxRedirects number optional 10 Maximum number of HTTP redirects to follow. Only applies when allowRedirects is true.
verify boolean optional true Whether to verify SSL/TLS certificates. Set to false for testing environments or internal sites with self-signed certificates.
auth object optional null HTTP Basic or Digest authentication credentials. The object should contain username (string) and password (string).
sessionId string optional null An existing session ID to associate this request with. When provided, the request uses the session's browser context, cookies, and fingerprint. The session must be active and not expired.

Request Examples

The following examples demonstrate how to use the synchronous execute endpoint in different programming languages and for different use cases. All examples show complete, working code that you can copy and run directly. The key difference from the asynchronous workflow is that you get the full result in the response body without needing to poll a separate endpoint. Remember to replace YOUR_API_KEY with your actual BBRE API key.

Basic Synchronous GET Request

The simplest synchronous request. You send the URL and receive the complete result in a single HTTP call. No task ID, no polling, no second request. The response includes the status code, headers, body, cookies, and browser profile information.

JavaScript 
const axios = require("axios");

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

async function executeSyncRequest() {
  const response = await axios.post(
    API_BASE + "/request/execute",
    {
      url: "https://example.com/products"
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      },
      timeout: 130000
    }
  );

  const task = response.data.data.task;
  console.log("Status:", task.status);
  console.log("HTTP Status Code:", task.result.statusCode);
  console.log("Body Length:", task.result.body.length);
  console.log("Processing Time:", response.data.data.processingTime, "ms");

  return task.result;
}

executeSyncRequest();
Python 
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 + "/request/execute",
    headers=headers,
    json={
        "url": "https://example.com/products"
    },
    timeout=130
)

data = response.json()
task = data["data"]["task"]
print("Status:", task["status"])
print("HTTP Status Code:", task["result"]["statusCode"])
print("Body Length:", len(task["result"]["body"]))
print("Processing Time:", data["data"]["processingTime"], "ms")
Bash 
curl -X POST https://bbre-solver-api.mydisct.com/request/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  --max-time 130 \
  -d '{
    "url": "https://example.com/products"
  }'

Synchronous POST Request with Body

This example sends a POST request with a JSON body through the synchronous endpoint. This pattern is common when you need to submit data to an API that is behind bot protection and you want the response immediately without implementing a polling loop.

JavaScript 
const axios = require("axios");

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

async function syncPostRequest() {
  const response = await axios.post(
    API_BASE + "/request/execute",
    {
      url: "https://api.example.com/v2/search",
      method: "POST",
      headers: {
        "Accept": "application/json",
        "X-Requested-With": "XMLHttpRequest"
      },
      body: {
        query: "laptop",
        category: "electronics",
        page: 1,
        limit: 50
      },
      mode: "passive",
      sensibility: "medium",
      timeout: 60
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      },
      timeout: 70000
    }
  );

  const result = response.data.data.task.result;
  console.log("Status Code:", result.statusCode);
  console.log("Response Body:", result.body);

  return result;
}

syncPostRequest();
Python 
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 + "/request/execute",
    headers=headers,
    json={
        "url": "https://api.example.com/v2/search",
        "method": "POST",
        "headers": {
            "Accept": "application/json",
            "X-Requested-With": "XMLHttpRequest"
        },
        "body": {
            "query": "laptop",
            "category": "electronics",
            "page": 1,
            "limit": 50
        },
        "mode": "passive",
        "sensibility": "medium",
        "timeout": 60
    },
    timeout=70
)

data = response.json()
result = data["data"]["task"]["result"]
print("Status Code:", result["statusCode"])
print("Response Body:", result["body"])
Bash 
curl -X POST https://bbre-solver-api.mydisct.com/request/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  --max-time 70 \
  -d '{
    "url": "https://api.example.com/v2/search",
    "method": "POST",
    "headers": {
      "Accept": "application/json",
      "X-Requested-With": "XMLHttpRequest"
    },
    "body": {
      "query": "laptop",
      "category": "electronics",
      "page": 1,
      "limit": 50
    },
    "mode": "passive",
    "sensibility": "medium",
    "timeout": 60
  }'

Advanced Synchronous Request with Adaptive Mode

This example demonstrates a fully configured synchronous request using adaptive mode with high sensibility, a custom proxy, browser fingerprint, and cookies. This configuration is designed for accessing heavily protected websites that employ multiple layers of bot detection including JavaScript challenges, browser fingerprinting, and behavioral analysis.

JavaScript 
const axios = require("axios");

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

async function advancedSyncRequest() {
  const response = await axios.post(
    API_BASE + "/request/execute",
    {
      url: "https://protected-site.example.com/dashboard",
      method: "GET",
      mode: "adaptive",
      sensibility: "high",
      timeout: 180,
      fingerprint: {
        platform: "Win32",
        timezone: "America/New_York",
        language: "en-US",
        screen: { width: 1920, height: 1080 }
      },
      proxy: {
        host: "us-proxy.example.com",
        port: 8080,
        username: "proxyuser",
        password: "proxypass"
      },
      cookies: {
        session_token: "eyJhbGciOiJIUzI1NiJ9.abc123",
        user_pref: "theme=dark"
      },
      headers: {
        "Accept": "text/html,application/xhtml+xml",
        "Accept-Encoding": "gzip, deflate, br"
      },
      allowRedirects: true,
      maxRedirects: 5,
      verify: true
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      },
      timeout: 190000
    }
  );

  const task = response.data.data.task;
  const result = task.result;
  console.log("Task ID:", task.id);
  console.log("Status Code:", result.statusCode);
  console.log("Body Length:", result.body.length);
  console.log("Cookies:", JSON.stringify(result.cookies));
  console.log("Profile:", JSON.stringify(result.profile));
  console.log("Processing Time:", response.data.data.processingTime, "ms");

  return result;
}

advancedSyncRequest();
Python 
import requests
import json

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 + "/request/execute",
    headers=headers,
    json={
        "url": "https://protected-site.example.com/dashboard",
        "method": "GET",
        "mode": "adaptive",
        "sensibility": "high",
        "timeout": 180,
        "fingerprint": {
            "platform": "Win32",
            "timezone": "America/New_York",
            "language": "en-US",
            "screen": {"width": 1920, "height": 1080}
        },
        "proxy": {
            "host": "us-proxy.example.com",
            "port": 8080,
            "username": "proxyuser",
            "password": "proxypass"
        },
        "cookies": {
            "session_token": "eyJhbGciOiJIUzI1NiJ9.abc123",
            "user_pref": "theme=dark"
        },
        "headers": {
            "Accept": "text/html,application/xhtml+xml",
            "Accept-Encoding": "gzip, deflate, br"
        },
        "allowRedirects": True,
        "maxRedirects": 5,
        "verify": True
    },
    timeout=190
)

data = response.json()
task = data["data"]["task"]
result = task["result"]
print("Task ID:", task["id"])
print("Status Code:", result["statusCode"])
print("Body Length:", len(result["body"]))
print("Cookies:", json.dumps(result["cookies"]))
print("Processing Time:", data["data"]["processingTime"], "ms")
Bash 
curl -X POST https://bbre-solver-api.mydisct.com/request/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  --max-time 190 \
  -d '{
    "url": "https://protected-site.example.com/dashboard",
    "method": "GET",
    "mode": "adaptive",
    "sensibility": "high",
    "timeout": 180,
    "fingerprint": {
      "platform": "Win32",
      "timezone": "America/New_York",
      "language": "en-US",
      "screen": {"width": 1920, "height": 1080}
    },
    "proxy": {
      "host": "us-proxy.example.com",
      "port": 8080,
      "username": "proxyuser",
      "password": "proxypass"
    },
    "cookies": {
      "session_token": "eyJhbGciOiJIUzI1NiJ9.abc123",
      "user_pref": "theme=dark"
    },
    "headers": {
      "Accept": "text/html,application/xhtml+xml",
      "Accept-Encoding": "gzip, deflate, br"
    },
    "allowRedirects": true,
    "maxRedirects": 5,
    "verify": true
  }'

Using the /request/sync Alias

The /request/sync endpoint is a complete alias for /request/execute. Both paths route to the same controller function, accept the same parameters, and return the same response format. The alias exists purely for developer convenience. Some developers find /request/sync more intuitive when contrasting it with the asynchronous /request/create endpoint. You can use either URL interchangeably throughout your application without any difference in behavior or performance.

JavaScript 
const axios = require("axios");

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

async function usingSyncAlias() {
  const response = await axios.post(
    API_BASE + "/request/sync",
    {
      url: "https://example.com/data",
      mode: "passive"
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      },
      timeout: 130000
    }
  );

  console.log("Success:", response.data.success);
  console.log("Body:", response.data.data.task.result.body.substring(0, 200));

  return response.data.data.task.result;
}

usingSyncAlias();
Python 
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 + "/request/sync",
    headers=headers,
    json={
        "url": "https://example.com/data",
        "mode": "passive"
    },
    timeout=130
)

data = response.json()
print("Success:", data["success"])
print("Body:", data["data"]["task"]["result"]["body"][:200])
Bash 
curl -X POST https://bbre-solver-api.mydisct.com/request/sync \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  --max-time 130 \
  -d '{
    "url": "https://example.com/data",
    "mode": "passive"
  }'

Response Format

The synchronous execute endpoint returns the complete task result directly in the HTTP response. Unlike the asynchronous workflow where you receive a task ID and poll separately, the response from this endpoint contains the full result including the HTTP status code, response headers, response body, cookies, and browser profile information. The response also includes the processing time in milliseconds, which tells you how long the BBRE engine spent processing your request.

Success Response (200)

JSON 
{
  "success": true,
  "service": "MyDisct Solver BBRE",
  "data": {
    "task": {
      "id": "task_abc123def456",
      "status": "completed",
      "result": {
        "statusCode": 200,
        "headers": {
          "content-type": "text/html; charset=utf-8",
          "server": "nginx",
          "x-powered-by": "Express",
          "cache-control": "no-cache"
        },
        "body": "<html><head><title>Example</title></head><body>...</body></html>",
        "cookies": {
          "session": "abc123xyz",
          "preferences": "lang=en"
        },
        "profile": {
          "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
          "platform": "Win32",
          "screenWidth": 1920,
          "screenHeight": 1080,
          "timezone": "America/New_York",
          "locale": "en-US",
          "deviceMemory": 8,
          "hardwareConcurrency": 8,
          "webglVendor": "Google Inc. (NVIDIA)",
          "webglRenderer": "ANGLE (NVIDIA GeForce GTX 1080)"
        }
      }
    },
    "processingTime": 3456
  }
}
Field Type Description
success boolean Always true for successful requests.
service string Always "MyDisct Solver BBRE". Identifies the service that processed the request.
data.task.id string The unique task identifier. Even though this is a synchronous request, a task is still created internally for tracking and billing purposes.
data.task.status string The task status. Always "completed" for successful synchronous responses.
data.task.result.statusCode number The HTTP status code returned by the target website.
data.task.result.headers object The HTTP response headers returned by the target website as key-value pairs.
data.task.result.body string The response body from the target website. For HTML pages, this is the full HTML content. For API responses, this is the raw response text.
data.task.result.cookies object Cookies set by the target website during the request as key-value pairs.
data.task.result.profile object The browser fingerprint profile used for this request. Contains attributes like userAgent, platform, screen dimensions, timezone, locale, device memory, CPU cores, and WebGL information.
data.processingTime number The total processing time in milliseconds. This measures how long the BBRE engine spent processing the request, not including network latency between your application and the API.

Synchronous vs Asynchronous Comparison

The BBRE API offers two distinct approaches for sending requests: synchronous (this endpoint) and asynchronous (POST /request/create + POST /request/result). Both approaches process the request through the same BBRE engine with the same modes, sensibility levels, and fingerprinting capabilities. The difference is entirely in how your application interacts with the API. Understanding when to use each approach is critical for building efficient and reliable integrations.

Aspect Synchronous (execute/sync) Asynchronous (create + result)
API Calls Single call. Send parameters, receive result. Two calls minimum. Create task, then poll for result.
Connection HTTP connection stays open until processing completes or times out. Create call returns immediately. Polling calls are short-lived.
Default Timeout 120 seconds. Higher default to accommodate the open connection. 30 seconds. Lower default since polling handles the wait.
Task Status Task is created with status "processing" and returned as "completed" in the same response. Task is created with status "processing". You poll until it becomes "completed" or "failed".
Concurrency Each request occupies an HTTP connection for the full duration. Limited by your HTTP client's connection pool. Create calls return instantly. You can submit hundreds of tasks and poll them independently.
Error Detection Errors are returned immediately in the response. Timeout errors return 408 status. Creation errors return immediately. Processing errors are detected during polling.
Code Complexity Minimal. A single HTTP POST call with error handling. Moderate. Requires implementing a polling loop with interval management and timeout logic.
Balance Handling Balance is deducted before processing and refunded on failure. Balance is deducted at task creation and refunded on failure.
Best For Scripts, prototyping, low-volume requests, simple integrations, CLI tools. Production systems, high-volume pipelines, concurrent processing, microservices.

When to Use Synchronous vs Asynchronous

Choosing between synchronous and asynchronous execution depends on your specific use case, the volume of requests you need to process, and the architecture of your application. Here are detailed guidelines for making the right choice.

Use Synchronous When:

  • Prototyping and testing: You are exploring the BBRE API for the first time and want to see results quickly without writing polling logic. The synchronous endpoint lets you test different configurations with minimal code.
  • Single-request scripts: You have a script that needs to fetch one page or make one API call through BBRE. The overhead of implementing a polling loop is not justified for a single request.
  • Sequential processing: Your application processes URLs one at a time and waits for each result before moving to the next. In this case, the synchronous endpoint simplifies your code without any performance penalty.
  • CLI tools: You are building a command-line tool where the user expects to see the result after running a command. The synchronous endpoint maps naturally to this interaction pattern.
  • Low-volume integrations: You process fewer than 10 requests per minute and do not need concurrent execution. The synchronous endpoint keeps your integration simple and maintainable.

Use Asynchronous When:

  • High-volume processing: You need to process hundreds or thousands of URLs. The asynchronous workflow lets you submit all tasks quickly and poll for results in parallel, maximizing throughput.
  • Concurrent execution: You want to process multiple requests simultaneously. With the asynchronous approach, you can submit 50 tasks in rapid succession and then poll for all results concurrently.
  • Long-running requests: You are using adaptive mode with high sensibility on complex pages that may take 60 seconds or more. The asynchronous approach avoids holding HTTP connections open for extended periods.
  • Microservice architectures: Your system uses message queues or event-driven patterns. The asynchronous workflow fits naturally: submit tasks from one service, poll for results from another.
  • Timeout control: You need fine-grained control over how long to wait for results. The polling approach lets you implement custom timeout logic, exponential backoff, and graceful degradation.

Timeout Management

Timeout management is especially important for synchronous requests because your HTTP connection stays open for the entire processing duration. There are two timeout values you need to consider: the BBRE processing timeout (the timeout parameter in the request body) and your HTTP client timeout (the timeout setting in axios, requests, or curl). These two timeouts serve different purposes and must be configured correctly to avoid unexpected behavior.

BBRE Processing Timeout

The timeout parameter in the request body controls how long the BBRE engine will spend processing your request. If the engine cannot complete the request within this time, it stops processing and returns a 408 SERVICE_TIMEOUT error. The default is 120 seconds for synchronous requests. Set this based on the expected processing time for your target site and mode:

  • Passive mode, simple sites: 15-30 seconds is usually sufficient.
  • Passive mode, slow servers: 30-60 seconds to account for server response time.
  • Adaptive mode, standard sites: 60-90 seconds for browser startup, rendering, and JavaScript execution.
  • Adaptive mode, heavily protected sites: 120-180 seconds for full evasion techniques with high sensibility.

HTTP Client Timeout

Your HTTP client (axios, requests, curl) also has its own timeout setting. This timeout must be higher than the BBRE processing timeout to ensure you receive the BBRE error response rather than a client-side timeout error. A good rule is to set your HTTP client timeout to the BBRE timeout plus 10 seconds. This extra buffer accounts for network latency and API processing overhead.

JavaScript 
const axios = require("axios");

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

const bbreTimeout = 90;

async function requestWithProperTimeout() {
  const response = await axios.post(
    API_BASE + "/request/execute",
    {
      url: "https://example.com/heavy-page",
      mode: "adaptive",
      sensibility: "high",
      timeout: bbreTimeout
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
      },
      timeout: (bbreTimeout + 10) * 1000
    }
  );

  return response.data.data.task.result;
}

requestWithProperTimeout();
Important: Client Timeout Must Exceed BBRE Timeout

If your HTTP client timeout is shorter than the BBRE processing timeout, your client will disconnect before the BBRE engine finishes. You will receive a client-side timeout error instead of the actual BBRE response (which could be either a success or a structured error). The BBRE engine will still complete processing and deduct the balance, but you will not receive the result. Always set your client timeout to at least bbreTimeout + 10 seconds.

Error Responses

When a synchronous request fails, the API returns an error response with an appropriate HTTP status code, an error code string for programmatic handling, and a human-readable message. The synchronous endpoint can return all the same errors as the asynchronous create endpoint, plus the 408 SERVICE_TIMEOUT error which occurs when the BBRE engine cannot complete processing within the specified timeout.

Timeout Error (408)

This error is specific to the synchronous endpoint. It occurs when the BBRE engine cannot finish processing the request within the timeout period. The balance deducted for this request is automatically refunded to your account.

JSON 
{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": "SERVICE_TIMEOUT",
  "message": "Request processing timed out"
}

Authentication Error (401)

JSON 
{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": "API_KEY_REQUIRED",
  "message": "API key is required. Provide it via x-api-key header."
}

Insufficient Balance Error (402)

JSON 
{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": "INSUFFICIENT_BALANCE",
  "message": "Insufficient balance for this request",
  "required": 0.005,
  "current_balance": 0.002,
  "deficit": 0.003
}

Complete Error Code Reference

HTTP Status Error Code Cause Solution
400 URL_REQUIRED The url parameter is missing from the request body. Include a valid URL in the request body. The URL must include the protocol (http:// or https://).
400 INVALID_MODE The mode parameter contains an invalid value. Use either "passive" or "adaptive" as the mode value. Values are case-sensitive and must be lowercase.
400 INVALID_SENSIBILITY The sensibility parameter contains an invalid value. Use "low", "medium", or "high" as the sensibility value. Values are case-sensitive and must be lowercase.
400 INVALID_REQUEST The request body contains invalid or malformed data. Check that the request body is valid JSON and all parameter types match the expected types described in the parameter table.
401 API_KEY_REQUIRED No API key was provided in the request headers. Include your API key in the x-api-key or apikey HTTP header.
402 INSUFFICIENT_BALANCE Your account balance is too low to cover the request cost. Add funds to your account through the MyDisct Solver dashboard. The error response includes the required amount, your current_balance, and the deficit.
403 INVALID_API_KEY The provided API key does not match any active account. Verify that you are using the correct API key from your MyDisct Solver dashboard. Check for extra whitespace or truncated characters.
403 ACCOUNT_SUSPENDED Your account has been suspended due to a policy violation. Contact MyDisct Solver support to resolve the suspension.
403 ACCOUNT_INACTIVE Your account is not currently active. Log in to the MyDisct Solver dashboard and activate your account.
408 SERVICE_TIMEOUT The BBRE engine could not complete processing within the specified timeout period. Increase the timeout parameter value. For adaptive mode with high sensibility, use at least 120 seconds. If the target site is consistently slow, consider switching to the asynchronous workflow which gives you more control over wait times. Balance is automatically refunded for timed-out requests.
500 SERVICE_ERROR An internal error occurred while processing the request. Retry the request after a short delay. If the error persists, contact support.
500 PRICING_NOT_CONFIGURED The pricing configuration for BBRE requests is not set up. This is a server-side configuration issue. Contact MyDisct Solver support.

Error Handling Example

JavaScript 
const axios = require("axios");

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

async function syncRequestWithErrorHandling(url, options) {
  try {
    const bbreTimeout = options.timeout || 120;

    const response = await axios.post(
      API_BASE + "/request/execute",
      { url, ...options },
      {
        headers: {
          "Content-Type": "application/json",
          "x-api-key": API_KEY
        },
        timeout: (bbreTimeout + 10) * 1000
      }
    );

    return response.data.data.task.result;
  } catch (error) {
    if (error.response) {
      const data = error.response.data;
      const status = error.response.status;

      if (status === 408) {
        console.log("Request timed out. Consider increasing the timeout value.");
        console.log("Current timeout:", options.timeout || 120, "seconds");
      } else if (status === 401) {
        console.log("Authentication failed. Check your API key.");
      } else if (status === 402) {
        console.log("Insufficient balance.");
        console.log("Required:", data.required);
        console.log("Current balance:", data.current_balance);
      } else if (status === 403) {
        console.log("Access denied:", data.error);
      } else if (status === 400) {
        console.log("Invalid request:", data.error, data.message);
      } else {
        console.log("Server error:", status, data.error);
      }
    } else if (error.code === "ECONNABORTED") {
      console.log("HTTP client timeout. The BBRE engine may still be processing.");
      console.log("Increase your HTTP client timeout to exceed the BBRE timeout.");
    } else {
      console.log("Network error:", error.message);
    }

    return null;
  }
}

syncRequestWithErrorHandling("https://example.com/data", {
  mode: "adaptive",
  sensibility: "high",
  timeout: 90
});
Python 
import requests

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

def sync_request_with_error_handling(url, options=None):
    if options is None:
        options = {}

    bbre_timeout = options.get("timeout", 120)
    payload = {"url": url}
    payload.update(options)

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

    try:
        response = requests.post(
            API_BASE + "/request/execute",
            headers=headers,
            json=payload,
            timeout=bbre_timeout + 10
        )

        if response.status_code == 200:
            data = response.json()
            return data["data"]["task"]["result"]

        data = response.json()

        if response.status_code == 408:
            print("Request timed out. Consider increasing the timeout value.")
        elif response.status_code == 401:
            print("Authentication failed. Check your API key.")
        elif response.status_code == 402:
            print("Insufficient balance. Required:", data.get("required"))
        elif response.status_code == 403:
            print("Access denied:", data.get("error"))
        elif response.status_code == 400:
            print("Invalid request:", data.get("error"), data.get("message"))
        else:
            print("Server error:", response.status_code, data.get("error"))

    except requests.exceptions.Timeout:
        print("HTTP client timeout. Increase your client timeout.")
    except requests.exceptions.ConnectionError:
        print("Network error. Check your internet connection.")

    return None

result = sync_request_with_error_handling(
    "https://example.com/data",
    {"mode": "adaptive", "sensibility": "high", "timeout": 90}
)

Using the Node.js SDK

The mydisctsolver-bbre Node.js SDK provides two ways to make synchronous requests. You can either use the client.request() method with the sync: true option, or use the convenience HTTP methods (client.get(), client.post(), etc.) which use the asynchronous workflow by default but can be configured for synchronous execution. The SDK handles the HTTP client timeout automatically, setting it to the BBRE timeout plus 10 seconds to ensure you always receive the BBRE response.

Synchronous Request with client.request()

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

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

async function syncWithSDK() {
  const result = await client.request({
    url: "https://example.com/products",
    sync: true
  });

  console.log("Status Code:", result.statusCode);
  console.log("Body Length:", result.body.length);
  console.log("Cookies:", JSON.stringify(result.cookies));
  console.log("Processing Time:", result.processingTime, "ms");

  return result;
}

syncWithSDK();

Using Convenience HTTP Methods

The convenience methods (get, post, put, delete, patch, head, options) use the asynchronous workflow by default (create + poll). To use them with the synchronous endpoint, pass sync: true in the options object.

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

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

async function sdkConvenienceMethods() {
  const getResult = await client.get("https://example.com/products", {
    sync: true,
    timeout: 60
  });
  console.log("GET Status:", getResult.statusCode);

  const postResult = await client.post(
    "https://api.example.com/search",
    {
      query: "laptop",
      category: "electronics"
    },
    {
      sync: true,
      headers: { "Accept": "application/json" },
      timeout: 60
    }
  );
  console.log("POST Status:", postResult.statusCode);
  console.log("POST Body:", postResult.body);

  return { getResult, postResult };
}

sdkConvenienceMethods();

Synchronous Request with Adaptive Mode

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

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

async function syncAdaptiveRequest() {
  const result = await client.request({
    url: "https://protected-site.example.com/dashboard",
    method: "GET",
    mode: "adaptive",
    sensibility: "high",
    timeout: 180,
    sync: true,
    fingerprint: {
      platform: "Win32",
      timezone: "America/New_York",
      language: "en-US"
    },
    proxy: {
      host: "us-proxy.example.com",
      port: 8080,
      username: "proxyuser",
      password: "proxypass"
    }
  });

  console.log("Status Code:", result.statusCode);
  console.log("Body Length:", result.body.length);
  console.log("Profile:", JSON.stringify(result.profile));

  return result;
}

syncAdaptiveRequest();

The SDK internally calls POST /request/execute when sync: true is set, and POST /request/create followed by polling POST /request/result when sync is false or omitted. For more details on the SDK, see the Node.js SDK Overview.

""

Pricing and Balance

Each synchronous request has an associated cost that is deducted from your account balance before processing begins. The price is determined by the BBRE_REQUEST pricing tier configured in the system. The balance deduction happens atomically within a database transaction to ensure consistency. If the BBRE engine fails to process your request or the request times out, the deducted amount is automatically refunded to your account. You do not need to take any action to receive the refund; it happens as part of the error handling pipeline. The pricing is identical for synchronous and asynchronous requests. There is no additional cost for using the synchronous endpoint.

You can check your current balance at any time using the Account Balance endpoint. If your balance is insufficient for a request, the API returns a 402 INSUFFICIENT_BALANCE error that includes the required amount, your current balance, and the deficit.

Best Practices

Always Set Your HTTP Client Timeout Higher Than the BBRE Timeout

The most common mistake with synchronous requests is setting the HTTP client timeout equal to or lower than the BBRE processing timeout. When this happens, your client disconnects before the BBRE engine finishes, and you receive a generic client-side timeout error instead of the structured BBRE response. Set your HTTP client timeout to the BBRE timeout plus at least 10 seconds. For example, if your BBRE timeout is 120 seconds, set your axios timeout to 130000 milliseconds, your Python requests timeout to 130 seconds, or your curl max-time to 130.

Use Synchronous for Prototyping, Asynchronous for Production

The synchronous endpoint is excellent for testing, prototyping, and low-volume use cases because it eliminates the complexity of polling. However, for production systems that process more than a handful of requests per minute, the asynchronous workflow is more robust. It gives you better control over concurrency, timeout handling, and error recovery. Start with the synchronous endpoint to validate your integration, then migrate to the asynchronous workflow when you move to production. If you are using the Node.js SDK, switching between sync and async is as simple as toggling the sync option.

Match Timeout to Mode and Sensibility

Different mode and sensibility combinations have very different processing times. Passive mode with low sensibility typically completes in 2-5 seconds, while adaptive mode with high sensibility can take 30-90 seconds or more. Set your timeout to approximately 2-3 times the expected processing time for your specific configuration. This gives enough margin for slower-than-average requests without wasting time on requests that are clearly stuck. For passive mode, a timeout of 30-60 seconds is usually appropriate. For adaptive mode with high sensibility, use 120-180 seconds.

Implement Retry Logic with Escalation

When a synchronous request fails with a 408 SERVICE_TIMEOUT or 500 SERVICE_ERROR, implement a retry strategy that escalates the configuration. On the first retry, increase the timeout. On the second retry, switch from passive to adaptive mode if you were using passive. On the third retry, increase the sensibility level. This progressive escalation approach maximizes your success rate while keeping costs low for requests that succeed with minimal configuration.

Check Balance Before Batch Processing

If you are processing multiple URLs sequentially using the synchronous endpoint, check your account balance before starting the batch. Use the Account Balance endpoint to verify you have sufficient funds for the entire batch. This prevents the frustrating scenario where your batch fails halfway through due to insufficient balance. Calculate the expected cost by multiplying the per-request price by the number of URLs in your batch.

Common Issues

Issue 1: Client-Side Timeout Before BBRE Response

Problem

Your HTTP client throws a timeout error (ECONNABORTED in axios, ReadTimeout in Python requests) before the BBRE engine returns a response. The BBRE engine may still be processing the request, and the balance has already been deducted.

Solution: This happens when your HTTP client timeout is shorter than the BBRE processing timeout. The fix is straightforward: set your HTTP client timeout to the BBRE timeout plus 10 seconds. In axios, this means setting timeout: (bbreTimeout + 10) * 1000 (note that axios uses milliseconds). In Python requests, set timeout=bbre_timeout + 10 (Python uses seconds). In curl, use --max-time with the value in seconds. If you are using the Node.js SDK, the client timeout is handled automatically.

Issue 2: 408 SERVICE_TIMEOUT on Adaptive Mode Requests

Problem

Requests using adaptive mode with medium or high sensibility consistently return 408 SERVICE_TIMEOUT errors, even though the same URL works fine in a regular browser.

Solution: Adaptive mode with high sensibility involves launching a full browser, navigating to the page, waiting for JavaScript to execute, and applying human-like behavioral patterns. This process can take 30-90 seconds for complex pages. The default timeout of 120 seconds should be sufficient for most sites, but heavily protected sites with multiple challenge pages may need more time. Increase the timeout to 180 or even 240 seconds. Also consider whether you actually need adaptive mode. Many sites that appear to require it can actually be accessed with passive mode if you use the right fingerprint and sensibility settings. Try passive mode with high sensibility first, as it is significantly faster.

Issue 3: Confusion Between /request/execute and /request/sync

Problem

You are unsure whether to use /request/execute or /request/sync, or you are seeing different behavior between the two endpoints.

Solution: Both endpoints are completely identical. They map to the same controller function, accept the same parameters, and return the same response format. There is zero difference in behavior, performance, or pricing. The /request/sync path exists purely as a naming convenience. If you are seeing different behavior, the issue is likely in your request parameters or network conditions, not in the endpoint choice. Pick whichever URL you prefer and use it consistently.