BBRE Error Codes

Error Response Structure

When the BBRE API encounters an error during request processing, it returns a JSON response with a consistent structure that your application can parse programmatically. The response always includes the success field set to false, the service field set to "MyDisct Solver BBRE" to identify which service generated the error, and an error object containing the machine-readable code and the human-readable message. The HTTP status code of the response corresponds to the category of error: 400-level codes indicate client-side issues that you need to fix in your request, while 500-level codes indicate server-side issues that are typically transient and can be retried. Understanding this structure is the foundation for building robust error handling in your integration.

Standard Error Response

The following JSON structure is returned for every error response from the BBRE API. The error.code field is the primary identifier you should use in your error handling logic because it is stable across API versions and uniquely identifies the specific error condition. The error.message field provides a human-readable description suitable for logging or displaying to end users.

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Error Response with Details

Some error responses include an additional details field that provides more specific information about the error. This field is not present on all errors, so your parsing logic should treat it as optional. When present, the details field may contain information such as which specific parameter failed validation, what the accepted values are, or additional context about the server-side condition that caused the error.

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "INVALID_MODE",
    "message": "Invalid mode. Valid modes: passive, adaptive.",
    "details": "Received mode value: aggressive"
  }
}

Response Fields

Authentication Errors

Authentication errors occur when the BBRE API cannot verify your identity or when your credentials are missing, invalid, or associated with a problematic account state. Every request to the BBRE API requires a valid API key sent through the x-api-key or apikey HTTP header. If the API key is missing entirely, the API returns API_KEY_REQUIRED. If the key is present but does not match any active key in the system, the API returns INVALID_API_KEY. If the key is valid but there is a server-side issue during the validation process, the API returns API_KEY_VALIDATION_ERROR. Authentication errors are the most common errors encountered during initial integration because they surface immediately on the first request attempt. Once your API key is correctly configured, these errors should not appear in normal operation unless your key is rotated, revoked, or your account status changes.

Authentication Error Example

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "API_KEY_REQUIRED",
    "message": "API Key is required. Please provide it in the header as x-api-key or apikey."
  }
}

Account Errors

Account errors indicate that your API key is valid and was successfully verified, but your account is in a state that prevents the requested operation from being executed. These errors cover three distinct scenarios: your account has been suspended by an administrator (typically due to terms of service violations or suspicious activity), your account is inactive (it exists but has not been activated or has been deactivated), or your account does not have enough balance to cover the cost of the requested operation. Account errors require action on your part to resolve. Suspended and inactive accounts need to be addressed through the MyDisct Solver support team, while insufficient balance errors can be resolved by adding funds to your account through the dashboard. Unlike authentication errors which block all requests, account errors may be selective: for example, an account with insufficient balance can still make requests to free endpoints like /account/info and /account/balance, but will be blocked from creating requests or sessions that incur charges.

Account Error Example

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance. Please add funds to your account."
  }
}

Request Validation Errors

Request validation errors are returned when the BBRE API receives a request that contains invalid, malformed, or missing parameters. These errors are always HTTP 400 (Bad Request) responses, which means the problem is in your request and you need to fix it before retrying. The BBRE API validates request parameters before processing begins, so validation errors are returned immediately without consuming any account balance. This category covers a wide range of issues: missing required fields like the target URL, invalid values for enumerated parameters like mode and sensibility, malformed URL strings, invalid HTTP methods, out-of-range timeout values, and incorrectly structured proxy configurations. Each error code in this category tells you exactly which parameter failed validation and what the accepted values are, making it straightforward to identify and fix the issue. During development, you will likely encounter these errors frequently as you build and test your integration. In production, they should be rare if your request construction logic is correct, but you should still handle them gracefully because user input or dynamic data could introduce invalid values.

Request Validation Error Example

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "INVALID_MODE",
    "message": "Invalid mode. Valid modes: passive, adaptive."
  }
}

Task Errors

Task errors are specific to the asynchronous request workflow in the BBRE API. When you create a request using the POST /request/create endpoint, the API returns a taskId that you use to poll for results via POST /request/result. Task errors occur when there is a problem with this polling process: either you did not provide a task ID in your result request, or the task ID you provided does not correspond to any task in the system (or belongs to a different account). These errors are straightforward to diagnose and fix. The TASK_ID_REQUIRED error means you forgot to include the taskId parameter in your request body. The TASK_NOT_FOUND error means the task ID is present but does not match any existing task for your account. Task IDs are account-scoped, so you cannot access tasks created by other accounts even if you know their task IDs. Task IDs are also ephemeral and may be cleaned up after a period of time, so polling for very old task IDs may also return this error.

Task Error Example

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task not found or does not belong to this user."
  }
}

Session Errors

Session errors cover the full range of problems that can occur when working with BBRE sessions. Sessions are stateful browser contexts that maintain cookies, fingerprint profiles, and request history across multiple API calls. Because sessions have a lifecycle (created, active, expired, closed) and resource limits (maximum 10 active sessions per account), there are several error conditions specific to session management. The SESSION_NOT_FOUND error indicates that the session ID does not exist or belongs to a different account. SESSION_EXPIRED and SESSION_CLOSED indicate that the session existed but is no longer usable because it either timed out or was explicitly closed. SESSION_ID_REQUIRED means you forgot to include the session identifier in your request. SESSION_LIMIT_REACHED means you have hit the maximum number of concurrent active sessions and need to close one before creating a new one. Session errors are common in production applications that manage multiple concurrent sessions, and your error handling should account for all of these scenarios to build a resilient integration.

Session Error Example

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "SESSION_EXPIRED",
    "message": "Session has expired. Please create a new session."
  }
}

Browser Errors

Browser errors are specific to the adaptive mode browser automation features of the BBRE API. When you use the POST /browser/action endpoint to perform browser actions like navigating to pages, clicking elements, filling forms, or taking screenshots, the BBRE engine controls a real browser instance on the server side. Browser errors occur when the requested action cannot be completed: either because the action specification is missing or invalid, or because the browser encountered a problem while executing the action (element not found, page load timeout, JavaScript execution error, etc.). The ACTION_REQUIRED error is a validation error that means you did not specify what action to perform. The BROWSER_ACTION_FAILED error is a runtime error that means the browser attempted the action but it failed during execution. Browser action failures can be caused by many factors including incorrect CSS selectors, elements that are not visible or not interactable, pages that have not finished loading, or JavaScript errors on the target page.

Browser Error Example

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "BROWSER_ACTION_FAILED",
    "message": "Browser action failed. Please try again."
  }
}

Service Errors

Service errors indicate problems on the BBRE server side that are not caused by your request. These errors cover general server failures, temporary service unavailability, request timeouts, pricing configuration issues, and processor availability problems. Most service errors are transient and can be resolved by retrying the request after a short delay. The SERVICE_ERROR code is a catch-all for unexpected server failures. SERVICE_UNAVAILABLE indicates that the BBRE service is temporarily down for maintenance or experiencing high load. SERVICE_TIMEOUT means your request took longer than the maximum allowed processing time. PRICING_NOT_CONFIGURED is a rare configuration error that should be reported to support. NO_PROCESSOR_AVAILABLE means all BBRE processing nodes are busy and cannot accept new requests at this moment. When you encounter service errors, implement exponential backoff retry logic: wait 1 second before the first retry, 2 seconds before the second, 4 seconds before the third, and so on up to a maximum of 5 retries. If the error persists after all retries, log the error details and alert your monitoring system.

Service Error Example

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "MyDisct Solver BBRE service is temporarily unavailable. Please try again in a few moments."
  }
}

Rate Limiting

The BBRE API enforces rate limits to protect the service from excessive usage and ensure fair access for all users. When you exceed the allowed request rate, the API returns a RATE_LIMIT_EXCEEDED error with HTTP status 429. Rate limits are applied per API key and are calculated over a sliding time window. The exact rate limits depend on your account tier and may vary between endpoints. When you receive a rate limit error, you should stop sending requests immediately and wait before retrying. Implementing proper rate limit handling is essential for production applications because aggressive retry behavior when rate limited can extend the duration of the rate limit window and delay your recovery. The best approach is to implement a backoff strategy that progressively increases the wait time between retries when rate limited.

Rate Limit Error Example

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please wait a moment before trying again."
  }
}

Error Handling in Code

Proper error handling is the difference between a fragile integration that breaks at the first unexpected response and a production-ready system that gracefully handles every failure scenario. The BBRE API returns structured error responses that make it straightforward to implement comprehensive error handling in any programming language. The key principle is to always check the success field first, then branch on the error.code field to determine the appropriate action for each error type. The following examples demonstrate robust error handling patterns in JavaScript, Python, and cURL that you can adapt to your specific application architecture.

JavaScript Error Handling

In JavaScript, wrap your BBRE API calls in try-catch blocks and inspect the response body to determine the error type. The following example shows a complete error handling pattern that covers authentication errors, account errors, validation errors, session errors, rate limiting, and service errors with appropriate retry logic for transient failures.

const fetch = require("node-fetch");

const API_KEY = "your-api-key-here";
const BASE_URL = "https://bbre-solver-api.mydisct.com";

async function makeRequest(url, options) {
    const maxRetries = 3;
    let attempt = 0;

    while (attempt < maxRetries) {
        const response = await fetch(url, options);
        const data = await response.json();

        if (data.success) {
            return data;
        }

        const errorCode = data.error.code;

        if (errorCode === "API_KEY_REQUIRED" || errorCode === "INVALID_API_KEY") {
            throw new Error("Authentication failed: " + data.error.message);
        }

        if (errorCode === "ACCOUNT_SUSPENDED" || errorCode === "ACCOUNT_INACTIVE") {
            throw new Error("Account issue: " + data.error.message);
        }

        if (errorCode === "INSUFFICIENT_BALANCE") {
            throw new Error("No balance: " + data.error.message);
        }

        if (errorCode === "INVALID_REQUEST" || errorCode === "URL_REQUIRED" ||
            errorCode === "INVALID_URL" || errorCode === "INVALID_MODE" ||
            errorCode === "INVALID_SENSIBILITY" || errorCode === "INVALID_METHOD") {
            throw new Error("Validation error: " + data.error.message);
        }

        if (errorCode === "SESSION_EXPIRED" || errorCode === "SESSION_CLOSED") {
            throw new Error("Session ended: " + data.error.message);
        }

        if (errorCode === "SESSION_LIMIT_REACHED") {
            throw new Error("Too many sessions: " + data.error.message);
        }

        if (errorCode === "RATE_LIMIT_EXCEEDED") {
            const delay = Math.pow(2, attempt) * 2000;
            await new Promise(resolve => setTimeout(resolve, delay));
            attempt++;
            continue;
        }

        if (errorCode === "SERVICE_ERROR" || errorCode === "SERVICE_UNAVAILABLE" ||
            errorCode === "SERVICE_TIMEOUT" || errorCode === "NO_PROCESSOR_AVAILABLE") {
            const delay = Math.pow(2, attempt) * 1000;
            await new Promise(resolve => setTimeout(resolve, delay));
            attempt++;
            continue;
        }

        throw new Error("Unknown error: " + data.error.code + " - " + data.error.message);
    }

    throw new Error("Max retries exceeded");
}

async function createBBRERequest() {
    const result = await makeRequest(BASE_URL + "/request/execute", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": API_KEY
        },
        body: JSON.stringify({
            url: "https://example.com",
            mode: "passive",
            sensibility: "medium"
        })
    });

    console.log("Status:", result.solution.status);
    console.log("Body length:", result.solution.body.length);
}

createBBRERequest().catch(console.error);

Python Error Handling

In Python, use the requests library to make API calls and inspect the JSON response body for error information. The following example demonstrates a retry-capable request function that handles all BBRE error categories with appropriate backoff for transient errors and immediate failure for permanent errors.

import requests
import time

API_KEY = "your-api-key-here"
BASE_URL = "https://bbre-solver-api.mydisct.com"

PERMANENT_ERRORS = [
    "API_KEY_REQUIRED",
    "INVALID_API_KEY",
    "ACCOUNT_SUSPENDED",
    "ACCOUNT_INACTIVE",
    "INSUFFICIENT_BALANCE",
    "INVALID_REQUEST",
    "URL_REQUIRED",
    "INVALID_URL",
    "INVALID_MODE",
    "INVALID_SENSIBILITY",
    "INVALID_METHOD",
    "INVALID_TIMEOUT",
    "INVALID_PROXY",
    "TASK_ID_REQUIRED",
    "SESSION_ID_REQUIRED",
    "ACTION_REQUIRED",
    "SESSION_EXPIRED",
    "SESSION_CLOSED",
]

RETRYABLE_ERRORS = [
    "SERVICE_ERROR",
    "SERVICE_UNAVAILABLE",
    "SERVICE_TIMEOUT",
    "NO_PROCESSOR_AVAILABLE",
    "RATE_LIMIT_EXCEEDED",
    "API_KEY_VALIDATION_ERROR",
    "BROWSER_ACTION_FAILED",
]

def make_bbre_request(endpoint, payload):
    max_retries = 3
    attempt = 0

    while attempt < max_retries:
        response = requests.post(
            f"{BASE_URL}{endpoint}",
            json=payload,
            headers={
                "Content-Type": "application/json",
                "x-api-key": API_KEY
            }
        )

        data = response.json()

        if data.get("success"):
            return data

        error_code = data["error"]["code"]
        error_message = data["error"]["message"]

        if error_code in PERMANENT_ERRORS:
            raise Exception(f"Permanent error [{error_code}]: {error_message}")

        if error_code in RETRYABLE_ERRORS:
            delay = (2 ** attempt) * 1.5
            print(f"Retryable error [{error_code}], waiting {delay}s...")
            time.sleep(delay)
            attempt += 1
            continue

        raise Exception(f"Unexpected error [{error_code}]: {error_message}")

    raise Exception("Max retries exceeded")

result = make_bbre_request("/request/execute", {
    "url": "https://example.com",
    "mode": "passive",
    "sensibility": "medium"
})

print(f"Status: {result['solution']['status']}")
print(f"Body length: {len(result['solution']['body'])}")

cURL Error Handling

When using cURL from the command line or shell scripts, you can check the HTTP status code to determine if the request succeeded and parse the JSON response body to extract error details. The following example shows how to make a BBRE API request with cURL and handle the response in a bash script.

curl -s -w "\n%{http_code}" \
  -X POST "https://bbre-solver-api.mydisct.com/request/execute" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "url": "https://example.com",
    "mode": "passive",
    "sensibility": "medium"
  }'

The -w "\n%{http_code}" flag appends the HTTP status code to the output, making it easy to check the response status. A status code of 200 indicates success. Status codes in the 400 range indicate client errors that need to be fixed in your request. Status codes in the 500 range indicate server errors that may be retried. Parse the JSON response body to extract the error.code and error.message fields for detailed error information.

RESPONSE=$(curl -s -w "\n%{http_code}" \
  -X POST "https://bbre-solver-api.mydisct.com/request/execute" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{"url": "https://example.com", "mode": "passive"}')

HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [ "$HTTP_CODE" -eq 200 ]; then
  echo "Success"
  echo "$BODY" | python3 -m json.tool
elif [ "$HTTP_CODE" -eq 401 ]; then
  echo "Authentication error - check your API key"
elif [ "$HTTP_CODE" -eq 402 ]; then
  echo "Insufficient balance - add funds to your account"
elif [ "$HTTP_CODE" -eq 429 ]; then
  echo "Rate limited - wait before retrying"
  sleep 5
else
  echo "Error (HTTP $HTTP_CODE):"
  echo "$BODY" | python3 -m json.tool
fi

SDK Error Handling

The mydisctsolver-bbre Node.js SDK wraps the raw HTTP API and surfaces errors as JavaScript exceptions. When an API call fails, the SDK throws an error object that contains the same code and message fields from the API response, making it easy to handle errors using standard try-catch patterns. The SDK does not perform automatic retries for any error type, giving you full control over retry logic and error recovery strategies. Both the BBREClient and BBRESession classes throw errors in the same format, so your error handling code works consistently regardless of which class you are using. The BrowserAPI class, accessed through a session, also throws errors in the same format when browser actions fail.

BBREClient Error Handling

The BBREClient class throws errors for all API operations including requests, account queries, and session management. The error object includes the code property with the BBRE error code and the message property with the human-readable description.

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

const client = new BBREClient({ apiKey: "your-api-key-here" });

async function fetchPage() {
    try {
        const result = await client.request({
            url: "https://example.com",
            mode: "passive"
        });
        console.log("Page fetched, status:", result.solution.status);
    } catch (error) {
        if (error.code === "INSUFFICIENT_BALANCE") {
            console.log("Add funds to your account before making requests");
            return;
        }

        if (error.code === "INVALID_URL") {
            console.log("The URL format is invalid:", error.message);
            return;
        }

        if (error.code === "SERVICE_UNAVAILABLE" || error.code === "SERVICE_TIMEOUT") {
            console.log("Service temporarily unavailable, retrying in 3 seconds...");
            await new Promise(resolve => setTimeout(resolve, 3000));
            return fetchPage();
        }

        console.log("Unexpected error:", error.code, error.message);
    }
}

fetchPage();

BBRESession Error Handling

The BBRESession class adds session-specific errors on top of the standard BBRE errors. When working with sessions, you need to handle session lifecycle errors (SESSION_EXPIRED, SESSION_CLOSED) in addition to the standard request errors. A common pattern is to catch session expiration errors and automatically create a new session to continue the workflow.

const { BBRESession } = require("mydisctsolver-bbre");

async function sessionWorkflow() {
    let session = new BBRESession({
        apiKey: "your-api-key-here",
        mode: "adaptive",
        sensibility: "medium"
    });

    try {
        await session.start();
        console.log("Session started:", session.sessionId);

        const result = await session.request({ url: "https://example.com" });
        console.log("Page loaded, status:", result.solution.status);

        await session.browser.click({ selector: "button.submit" });
        console.log("Button clicked");

    } catch (error) {
        if (error.code === "SESSION_EXPIRED") {
            console.log("Session expired, creating new session...");
            session = new BBRESession({
                apiKey: "your-api-key-here",
                mode: "adaptive",
                sensibility: "medium"
            });
            await session.start();
            return;
        }

        if (error.code === "SESSION_LIMIT_REACHED") {
            console.log("Too many active sessions, close unused sessions first");
            return;
        }

        if (error.code === "BROWSER_ACTION_FAILED") {
            console.log("Browser action failed:", error.message);
            return;
        }

        console.log("Error:", error.code, error.message);
    } finally {
        try {
            await session.close();
        } catch (closeError) {
            console.log("Failed to close session:", closeError.message);
        }
    }
}

sessionWorkflow();

Error Object Structure

When the SDK throws an error, the error object has the following properties that you can use in your catch blocks for programmatic error handling.

Retry Strategy

Not all BBRE API errors should be retried. Some errors indicate permanent problems that require code changes or account actions to resolve, while others indicate transient conditions that will resolve on their own after a short wait. Retrying permanent errors wastes time and API calls, while failing to retry transient errors causes unnecessary failures in your application. The following classification helps you build an intelligent retry strategy that maximizes reliability without wasting resources.

Retryable Errors (Transient)

These errors indicate temporary conditions that are likely to resolve on their own. Implement exponential backoff when retrying: start with a 1-2 second delay and double it on each retry, up to a maximum of 5 retries. If the error persists after all retries, treat it as a permanent failure and escalate to your error reporting system.

Non-Retryable Errors (Permanent)

These errors indicate problems that will not resolve by retrying the same request. They require changes to your request parameters, account configuration, or application logic. Retrying these errors will produce the same result every time and should be avoided.

Exponential Backoff Implementation

The following JavaScript function implements exponential backoff with jitter, which is the recommended retry strategy for transient BBRE API errors. Jitter adds a small random component to the delay to prevent multiple clients from retrying at exactly the same time, which could cause a thundering herd effect on the server.

function calculateBackoff(attempt, baseDelay, maxDelay) {
    const exponentialDelay = baseDelay * Math.pow(2, attempt);
    const jitter = Math.random() * baseDelay;
    return Math.min(exponentialDelay + jitter, maxDelay);
}

async function retryableRequest(requestFn, maxRetries, baseDelay, maxDelay) {
    let lastError;

    for (let attempt = 0; attempt <= maxRetries; attempt++) {
        try {
            return await requestFn();
        } catch (error) {
            lastError = error;

            const retryableCodes = [
                "SERVICE_ERROR",
                "SERVICE_UNAVAILABLE",
                "SERVICE_TIMEOUT",
                "NO_PROCESSOR_AVAILABLE",
                "RATE_LIMIT_EXCEEDED",
                "API_KEY_VALIDATION_ERROR"
            ];

            if (!retryableCodes.includes(error.code)) {
                throw error;
            }

            if (attempt < maxRetries) {
                const delay = calculateBackoff(attempt, baseDelay, maxDelay);
                await new Promise(resolve => setTimeout(resolve, delay));
            }
        }
    }

    throw lastError;
}

Complete Error Code Reference

The following table provides a consolidated view of every error code that the BBRE API can return, sorted by HTTP status code. Use this table as a quick reference when you encounter an error and need to understand what it means and how to handle it. Each row includes the error code, HTTP status, category, and the default message returned by the API.

Error Handling Patterns

Beyond basic try-catch error handling, production applications benefit from structured error handling patterns that centralize error logic, provide consistent behavior across your codebase, and make it easy to add monitoring and alerting. The following patterns demonstrate advanced error handling approaches that work well with the BBRE API.

Error Classification Helper

Create a helper function that classifies BBRE errors into categories, making it easy to apply consistent handling logic throughout your application. This approach separates the error classification logic from the handling logic, keeping your code clean and maintainable.

function classifyBBREError(errorCode) {
    const classifications = {
        auth: ["API_KEY_REQUIRED", "INVALID_API_KEY", "API_KEY_VALIDATION_ERROR"],
        account: ["ACCOUNT_SUSPENDED", "ACCOUNT_INACTIVE", "INSUFFICIENT_BALANCE"],
        validation: [
            "INVALID_REQUEST", "URL_REQUIRED", "INVALID_URL", "INVALID_MODE",
            "INVALID_SENSIBILITY", "INVALID_METHOD", "INVALID_TIMEOUT",
            "INVALID_PROXY", "TASK_ID_REQUIRED", "SESSION_ID_REQUIRED",
            "ACTION_REQUIRED"
        ],
        session: [
            "SESSION_NOT_FOUND", "SESSION_EXPIRED", "SESSION_CLOSED",
            "SESSION_LIMIT_REACHED"
        ],
        task: ["TASK_NOT_FOUND"],
        browser: ["BROWSER_ACTION_FAILED"],
        service: [
            "SERVICE_ERROR", "SERVICE_UNAVAILABLE", "SERVICE_TIMEOUT",
            "PRICING_NOT_CONFIGURED", "NO_PROCESSOR_AVAILABLE"
        ],
        rateLimit: ["RATE_LIMIT_EXCEEDED"]
    };

    for (const [category, codes] of Object.entries(classifications)) {
        if (codes.includes(errorCode)) {
            return category;
        }
    }

    return "unknown";
}

async function handleBBRERequest(requestFn) {
    try {
        return await requestFn();
    } catch (error) {
        const category = classifyBBREError(error.code);

        if (category === "auth") {
            console.log("Authentication problem, check API key configuration");
        }

        if (category === "account") {
            console.log("Account issue, check dashboard for details");
        }

        if (category === "validation") {
            console.log("Request validation failed:", error.message);
        }

        if (category === "session") {
            console.log("Session problem:", error.code);
        }

        if (category === "service" || category === "rateLimit") {
            console.log("Transient error, safe to retry:", error.code);
        }

        throw error;
    }
}

Session Recovery Pattern

When working with BBRE sessions, implement automatic session recovery that detects expired or closed sessions and creates replacements transparently. This pattern is essential for long-running applications that maintain sessions over extended periods.

const { BBRESession } = require("mydisctsolver-bbre");

class ResilientSession {
    constructor(config) {
        this.config = config;
        this.session = null;
    }

    async ensureSession() {
        if (!this.session) {
            this.session = new BBRESession(this.config);
            await this.session.start();
        }
        return this.session;
    }

    async execute(operation) {
        try {
            const session = await this.ensureSession();
            return await operation(session);
        } catch (error) {
            if (error.code === "SESSION_EXPIRED" || error.code === "SESSION_CLOSED") {
                this.session = null;
                const session = await this.ensureSession();
                return await operation(session);
            }
            throw error;
        }
    }

    async close() {
        if (this.session) {
            try {
                await this.session.close();
            } catch (e) {
                console.log("Session close failed:", e.message);
            }
            this.session = null;
        }
    }
}

const resilient = new ResilientSession({
    apiKey: "your-api-key-here",
    mode: "adaptive",
    sensibility: "medium"
});

const result = await resilient.execute(async (session) => {
    return await session.request({ url: "https://example.com" });
});

await resilient.close();

Balance Check Before Requests

To avoid INSUFFICIENT_BALANCE errors in production, implement a pre-flight balance check that verifies your account has sufficient funds before making paid requests. This is especially useful for batch operations where you want to ensure all requests can be completed before starting the batch.

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

const client = new BBREClient({ apiKey: "your-api-key-here" });

async function checkBalanceAndExecute(urls) {
    const balanceData = await client.getBalance();
    const currentBalance = balanceData.balance;
    const estimatedCostPerRequest = 0.005;
    const totalEstimatedCost = urls.length * estimatedCostPerRequest;

    if (currentBalance < totalEstimatedCost) {
        console.log("Insufficient balance for batch operation");
        console.log("Current balance:", currentBalance);
        console.log("Estimated cost:", totalEstimatedCost);
        console.log("Deficit:", totalEstimatedCost - currentBalance);
        return;
    }

    const results = [];
    for (const url of urls) {
        const result = await client.request({ url, mode: "passive" });
        results.push(result);
    }

    return results;
}

checkBalanceAndExecute([
    "https://example.com/page1",
    "https://example.com/page2",
    "https://example.com/page3"
]);

Best Practices

Following these best practices will help you build a robust BBRE integration that handles errors gracefully, minimizes unnecessary failures, and provides a good experience for your end users.

• Always check the success field first. Before accessing any data in the API response, verify that success is true. This is the most reliable way to determine if the request succeeded, regardless of the HTTP status code. Some HTTP libraries may not throw exceptions for 4xx/5xx responses, so relying solely on exception handling can miss errors.
• Use error.code for programmatic error handling, not error.message. Error codes are stable identifiers that will not change between API versions. Error messages are human-readable descriptions that may be updated, rephrased, or translated in future versions. Build your branching logic around error codes and use messages only for logging and display purposes.
• Implement exponential backoff with jitter for retryable errors. When retrying transient errors like SERVICE_UNAVAILABLE, SERVICE_TIMEOUT, NO_PROCESSOR_AVAILABLE, and RATE_LIMIT_EXCEEDED, use exponential backoff (doubling the delay on each retry) with a small random jitter component. This prevents multiple clients from retrying at the same time and overwhelming the server.
• Classify errors into retryable and non-retryable categories. Not all errors should be retried. Authentication errors, validation errors, and account errors are permanent and will produce the same result on every retry. Service errors and rate limit errors are transient and should be retried with backoff. Implement this classification in a centralized error handler rather than duplicating the logic across your codebase.
• Set a maximum retry count and total timeout. Even for retryable errors, limit the number of retries (3-5 is typical) and the total time spent retrying (30-60 seconds). If the error persists beyond these limits, escalate to your error reporting system rather than retrying indefinitely. Infinite retry loops can consume resources and mask systemic issues.
• Check your balance before batch operations. If you are processing a large batch of URLs, check your account balance before starting the batch to ensure you have sufficient funds for all requests. This prevents partial batch completion where some requests succeed and others fail with INSUFFICIENT_BALANCE.
• Implement session recovery for long-running workflows. Sessions can expire or be closed unexpectedly. Build session recovery logic that detects SESSION_EXPIRED and SESSION_CLOSED errors and automatically creates a replacement session to continue the workflow without losing progress.
• Log error details for debugging. When an error occurs, log the full error response including the error code, message, HTTP status, and any details field. Also log the request that caused the error (excluding sensitive data like API keys) so you can reproduce and debug the issue later.
• Validate inputs before sending requests. Many validation errors can be prevented by validating your inputs before sending them to the API. Check that URLs start with http:// or https://, that mode values are "passive" or "adaptive", that sensibility values are "low", "medium", or "high", and that timeout values are positive numbers. Client-side validation is faster and cheaper than server-side validation.
• Monitor error rates in production. Track the frequency of each error code over time. A sudden increase in SERVICE_ERROR or SERVICE_UNAVAILABLE errors may indicate a systemic issue. A gradual increase in RATE_LIMIT_EXCEEDED errors may indicate that your application is growing beyond your current rate limits. Use this data to proactively address issues before they impact your users.

Common Issues

The following are the most frequently encountered issues when integrating with the BBRE API, along with their root causes and solutions. These issues are based on real support tickets and developer feedback.

API Key Not Being Sent in Headers

Symptom: Every request returns API_KEY_REQUIRED even though you have set the API key in your code.

Root Cause: The API key is being set as a query parameter, in the request body, or in a header with the wrong name. Some HTTP libraries have default behaviors that may strip custom headers or modify header names.

Solution: Verify that your HTTP client is sending the API key as an HTTP header with the exact name x-api-key or apikey. Use your browser's developer tools or a tool like Postman to inspect the actual headers being sent. If you are using a proxy or API gateway, check that it is not stripping custom headers from the request.

Session Expired During Long Workflow

Symptom: A multi-step workflow that uses sessions fails partway through with SESSION_EXPIRED.

Root Cause: Sessions have a limited lifetime. If there is a long delay between requests within a session (for example, waiting for user input or processing data between steps), the session may expire before the next request is made.

Solution: Implement session recovery logic that catches SESSION_EXPIRED errors and creates a new session to continue the workflow. If your workflow requires long pauses between steps, consider using the session status endpoint to check if the session is still active before making the next request. You can also increase the session timeout when creating the session, or make periodic keep-alive requests to prevent expiration.

Hitting the 10 Active Session Limit

Symptom: Creating a new session fails with SESSION_LIMIT_REACHED even though you thought all previous sessions were closed.

Root Cause: Sessions that are not explicitly closed remain active until they expire. If your application crashes or exits without closing its sessions, those sessions continue to count against your 10-session limit until they expire naturally.

Solution: Always close sessions in a finally block or cleanup handler to ensure they are closed even if your application encounters an error. Use the POST /account/sessions endpoint with {"status": "active"} to list your active sessions and identify any orphaned sessions that need to be closed. Implement a startup routine that checks for and closes any leftover sessions from previous runs.

BROWSER_ACTION_FAILED on Element Interaction

Symptom: Browser actions like click, fill, or type fail with BROWSER_ACTION_FAILED even though the selector appears correct.

Root Cause: The target element may not be visible, may be covered by another element (like a modal or overlay), may not have finished loading, or may be outside the current viewport. Dynamic pages that load content asynchronously are particularly prone to this issue.

Solution: Add explicit wait actions before interacting with elements. Use waitForElement or waitForSelector to ensure the element exists and is visible before clicking or filling it. If the element is below the fold, scroll to it first using the scroll action. For pages with overlays or modals, dismiss them before interacting with elements behind them. Use the screenshot action to capture the current page state for debugging.

Inconsistent INVALID_URL Errors

Symptom: Some URLs work fine while others that look similar return INVALID_URL.

Root Cause: The failing URLs may contain special characters that are not properly encoded, may be missing the protocol prefix, or may have invisible characters (like zero-width spaces or byte order marks) that were introduced during copy-paste operations.

Solution: Always encode URLs properly before sending them to the API. Use encodeURI() in JavaScript or urllib.parse.quote() in Python to handle special characters. Verify that the URL starts with http:// or https://. If you are reading URLs from a file or database, trim whitespace and check for invisible characters by logging the URL length and comparing it to the visible character count.

Related Documentation

The following documentation pages provide additional context and information that complements the error codes reference on this page.

• BBRE Engine Overview - Understand the BBRE architecture, operating modes (passive and adaptive), sensibility levels, and how the request processing pipeline works. This context helps you understand why certain errors occur and how to configure your requests to avoid them.
• BBRE Quick Start - Get started with the BBRE API in minutes. The quick start guide walks you through authentication, making your first request, and handling the response, with working code examples that include basic error handling.
• Create Request - Detailed documentation for the POST /request/create endpoint, including all parameters, their valid values, and example requests. Understanding the parameter requirements helps you avoid validation errors.
• Create Session - Documentation for session creation, including session configuration options, the 10-session limit, and session lifecycle management. Essential reading for understanding and preventing session-related errors.
• Browser Action - Complete reference for all browser actions available in adaptive mode, including the required parameters for each action type. Helps you construct valid browser action requests and avoid ACTION_REQUIRED and BROWSER_ACTION_FAILED errors.
• Node.js SDK Overview - Introduction to the mydisctsolver-bbre SDK, including installation, configuration, and how the SDK handles errors through exceptions. The SDK provides a higher-level interface that simplifies error handling compared to raw HTTP requests.
• Account Balance - Check your current account balance before making requests to avoid INSUFFICIENT_BALANCE errors. The balance endpoint is free to call and does not consume any credits.
• Account Sessions - List and manage your active sessions to avoid SESSION_LIMIT_REACHED errors. Use this endpoint to identify orphaned sessions that need to be closed.