Error Codes Reference - WebRun Documentation

Quick Fixes Summary

Jump to the solution for common errors:

Error Code	Quick Fix	Details
INVALID_API_KEY	Verify API key in Settings → API Keys	Link
SESSION_NOT_FOUND	Create new session with POST /start/start-session	Link
SESSION_EXPIRED	Sessions expire after maxDuration - create new one	Link
SESSION_LIMIT_REACHED	Terminate unused sessions or upgrade plan	Link
TASK_TIMEOUT	Increase maxDuration or simplify task	Link
TASK_ALREADY_RUNNING	Wait for completion or stop with newState: “stop”	Link
RATE_LIMIT_EXCEEDED	Wait before retrying, implement exponential backoff	Link
INSUFFICIENT_BALANCE	Add credits at webrun.ai/billing	Link
NAVIGATION_TIMEOUT	Retry request or check if website is accessible	Link
ELEMENT_NOT_FOUND	Rephrase task or wait for page load	Link

Error Response Format

All errors follow a consistent structure:

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": { /* Additional context */ }
}

HTTP Status Codes

Status	Meaning	Common Causes
`200`	Success	Request completed successfully
`400`	Bad Request	Invalid parameters, malformed JSON
`401`	Unauthorized	Missing or invalid API key
`402`	Payment Required	Insufficient account balance
`404`	Not Found	Session or task does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server-side issue
`503`	Service Unavailable	System maintenance or overload

Authentication Errors

INVALID_API_KEY

{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution: Verify your API key is correct and active in Settings → API Keys. Related:

API_KEY_EXPIRED

{
  "success": false,
  "error": "API key has expired",
  "code": "API_KEY_EXPIRED"
}

Solution: Generate a new API key in your account settings. Related:

Regenerating API Keys

UNAUTHORIZED

{
  "success": false,
  "error": "Authorization header missing",
  "code": "UNAUTHORIZED"
}

Solution: Include Authorization: Bearer YOUR_API_KEY header in all requests. Example:

const response = await fetch("https://connect.webrun.ai/start/start-session", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${YOUR_API_KEY}`
  },
  body: JSON.stringify({ prompt: "Navigate to example.com" })
});

Related:

Authentication Guide

Session Errors

SESSION_NOT_FOUND

{
  "success": false,
  "error": "Session a1b2c3d4e5f6 does not exist or has expired",
  "code": "SESSION_NOT_FOUND"
}

Causes:

Session was terminated
Session expired (5 min of inactivity)
Invalid sessionId

Solution: Create a new session with POST /start/start-session. Related:

SESSION_EXPIRED

{
  "success": false,
  "error": "Session expired after 300 seconds of inactivity",
  "code": "SESSION_EXPIRED"
}

Solution: Sessions expire after maxDuration. Create a new session for continuation. Best Practice:

// Set appropriate maxDuration
const session = await fetch("https://connect.webrun.ai/start/start-session", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    prompt: "Your task",
    maxDuration: 300000 // max task duration in milliseconds
  })
});

Related:

Session Timeouts

SESSION_LIMIT_REACHED

{
  "success": false,
  "error": "Maximum concurrent sessions reached (limit: 5)",
  "code": "SESSION_LIMIT_REACHED",
  "details": {
    "current": 5,
    "limit": 5
  }
}

Solution: Terminate unused sessions or upgrade your plan. Clean up sessions:

// Terminate session when done
await fetch("https://connect.webrun.ai/start/send-message", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    sessionId,
    message: { actionType: "state", newState: "terminate" }
  })
});

Related:

INSTANCE_UNAVAILABLE

{
  "success": false,
  "error": "No browser instances available",
  "code": "INSTANCE_UNAVAILABLE"
}

Solution: Wait and retry, or contact support if persistent. Retry with backoff:

async function createSessionWithRetry(prompt, apiKey, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch("https://connect.webrun.ai/start/start-session", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Authorization": `Bearer ${apiKey}`
        },
        body: JSON.stringify({ prompt })
      });

      const data = await response.json();
      if (response.ok) return data;

      if (data.code === "INSTANCE_UNAVAILABLE" && i < maxRetries - 1) {
        await new Promise(r => setTimeout(r, 2000 * Math.pow(2, i)));
        continue;
      }

      throw new Error(data.error);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Task Execution Errors

TASK_NOT_FOUND

{
  "success": false,
  "error": "Task x9y8z7w6v5u4 not found in session a1b2c3d4e5f6",
  "code": "TASK_NOT_FOUND"
}

Solution: Verify taskId and sessionId are correct. Related:

Task Polling

TASK_ALREADY_RUNNING

{
  "success": false,
  "error": "A task is already running in this session",
  "code": "TASK_ALREADY_RUNNING"
}

Solution: Wait for current task to complete or stop it with newState: "stop". Stop running task:

await fetch("https://connect.webrun.ai/start/send-message", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    sessionId,
    message: { actionType: "state", newState: "stop" }
  })
});

Related:

Task States

TASK_TIMEOUT

{
  "success": false,
  "error": "Task exceeded maximum duration of 60000ms",
  "code": "TASK_TIMEOUT",
  "usage": {
    "inputTokens": 25000,
    "outputTokens": 8000,
    "cost": 0.0245
  }
}

Solution: Increase maxDuration or simplify the task. Adjust timeouts:

const response = await fetch("https://connect.webrun.ai/start/run-task", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    sessionId,
    prompt: "Complex task",
    maxDuration: 120000 // 2 minutes
  })
});

Related:

INVALID_TASK_DETAILS

{
  "success": false,
  "error": "prompt cannot be empty",
  "code": "INVALID_TASK_DETAILS"
}

Solution: Provide a valid task description. Good task examples:

// Good - specific and actionable
prompt: "Navigate to example.com and click the 'Sign Up' button"

// Good - clear objective
prompt: "Search for 'laptop' on amazon.com and get the price of the first result"

// Bad - too vague
prompt: "do something"

Related:

Writing Effective Tasks

NAVIGATION_TIMEOUT

{
  "success": false,
  "error": "Navigation timeout after 30 seconds",
  "code": "NAVIGATION_TIMEOUT",
  "details": {
    "url": "https://example.com",
    "timeout": 30000
  }
}

Causes:

Slow website
Network issues
Website blocking automated access

Solution:

Retry the request
Check if website is accessible
Use startingUrl if navigating to a specific page

Example:

const session = await fetch("https://connect.webrun.ai/start/start-session", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    prompt: "Click the login button",
    startingUrl: "https://example.com/login" // Start directly at destination
  })
});

Related:

Navigation Options

PAGE_CRASH

{
  "success": false,
  "error": "Browser page crashed during execution",
  "code": "PAGE_CRASH"
}

Solution: Retry the task. If persistent, report to support with session details. Related:

Getting Help

ELEMENT_NOT_FOUND

{
  "success": false,
  "error": "Could not locate element matching criteria",
  "code": "ELEMENT_NOT_FOUND"
}

Causes:

Page structure changed
Element inside iframe
Element not yet loaded

Solution: Rephrase task description or wait for page load. Tips:

// Instead of: "Click the button"
// Try: "Click the blue 'Submit' button at the bottom of the form"

// For dynamic content:
prompt: "Wait for the results to load, then click the first product"

Related:

Task Best Practices

Rate Limiting & Network Errors

RATE_LIMIT_EXCEEDED

{
  "success": false,
  "message": "Rate limit exceeded. Please try again later."
}

Solution: Wait before retrying. Implement exponential backoff. Rate Limits by Endpoint:

POST /start/start-session: 10 requests/minute per user
POST /start/send-message: 10 requests/minute per user
POST /start/run-task: 10 requests/minute per user
GET /task/:sessionId/:taskId: No rate limit

Note: Rate limits are per user (API key owner), not per API key. Exponential Backoff Implementation:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      const data = await response.json();

      if (response.ok) return data;

      // Don't retry client errors (4xx) except rate limits
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        throw new Error(`${data.code}: ${data.error}`);
      }

      // Retry on 5xx errors and rate limits
      if (attempt < maxRetries - 1) {
        const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
        console.log(`Retry ${attempt + 1}/${maxRetries} after ${delay}ms`);
        await new Promise(r => setTimeout(r, delay));
        continue;
      }

      throw new Error(`${data.code}: ${data.error}`);

    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}

Related:

API Limits

Billing & Payment Errors

INSUFFICIENT_BALANCE

{
  "success": false,
  "error": "Insufficient account balance ($0.50 remaining, $2.00 required)",
  "code": "INSUFFICIENT_BALANCE",
  "details": {
    "balance": 0.50,
    "required": 2.00
  }
}

Solution: Add credits to your account at webrun.ai/billing. Monitor balance:

Check your balance regularly in the dashboard
Set up low balance alerts
Consider auto-recharge options

Related:

PAYMENT_FAILED

{
  "success": false,
  "error": "Payment method declined",
  "code": "PAYMENT_FAILED"
}

Solution: Update payment method in Settings → Billing. Common causes:

Expired card
Insufficient funds
Card issuer declined
Invalid billing address

Validation Errors

INVALID_PARAMETER

{
  "success": false,
  "error": "Invalid parameter 'maxDuration': must be at least 1000",
  "code": "INVALID_PARAMETER",
  "details": {
    "parameter": "maxDuration",
    "value": 500000,
    "min": 1000
  }
}

Solution: Check parameter requirements in API documentation. Parameter Ranges:

maxDuration: 1,000 - 300,000 ms (max task duration, default 5 minutes)
maxInputTokens: 1,000 - 100,000 tokens
maxOutputTokens: 100 - 50,000 tokens

Related:

API Reference

MISSING_REQUIRED_FIELD

{
  "success": false,
  "error": "Missing required field: task.prompt",
  "code": "MISSING_REQUIRED_FIELD",
  "details": {
    "field": "task.prompt"
  }
}

Solution: Include all required fields in request body. Required fields by endpoint: POST /start/start-session:

prompt (string)

POST /start/send-message:

sessionId (string)
message (object)

POST /start/run-task:

sessionId (string)
prompt (string)

Related:

API Reference

MCP-Specific Errors

MCP_SESSION_NOT_FOUND

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Session not found"
  }
}

Solution: Check your MCP session ID or reconnect to the SSE endpoint. Related:

MCP Integration

MCP_METHOD_NOT_FOUND

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found: invalid_method"
  }
}

Solution: Use valid MCP methods (tools/list, tools/call, etc.). Valid MCP methods:

tools/list
tools/call
resources/list
resources/read

Related:

MCP Methods

MCP_INVALID_REQUEST

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid request"
  }
}

Solution: Ensure request follows JSON-RPC 2.0 format with jsonrpc: "2.0". Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Related:

MCP Protocol

Error Handling Best Practices

Complete Error Handling Example

async function executeTaskWithRetry(prompt, apiKey) {
  let sessionId = null;

  try {
    // Create session with retry
    const session = await makeRequestWithRetry(
      "https://connect.webrun.ai/start/start-session",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Authorization": `Bearer ${apiKey}`
        },
        body: JSON.stringify({ prompt })
      }
    );

    sessionId = session.sessionId;

    // Execute task with guardrail handling
    const result = await executeTaskWithGuardrails(
      sessionId,
      prompt,
      apiKey
    );

    return result;

  } catch (error) {
    console.error("Task execution failed:", error.message);

    // Clean up session on error
    if (sessionId) {
      await terminateSession(sessionId, apiKey);
    }

    throw error;
  }
}

async function terminateSession(sessionId, apiKey) {
  try {
    await fetch("https://connect.webrun.ai/start/send-message", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${apiKey}`
      },
      body: JSON.stringify({
        sessionId,
        message: { actionType: "state", newState: "terminate" }
      })
    });
  } catch (error) {
    console.error("Failed to terminate session:", error.message);
  }
}

Handling Guardrails

async function executeTaskWithGuardrails(sessionId, prompt, apiKey) {
  let attempts = 0;
  const maxGuardrailAttempts = 3;

  while (attempts < maxGuardrailAttempts) {
    const result = await pollForResult(sessionId, taskId, apiKey);

    if (result.type === "task_completed") {
      return result;
    }

    if (result.type === "guardrail_trigger") {
      console.log(`Guardrail triggered: ${result.data.value}`);

      // Get user input
      const userInput = await promptUser(result.data.value);

      // Resume with input
      await fetch("https://connect.webrun.ai/start/send-message", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Authorization": `Bearer ${apiKey}`
        },
        body: JSON.stringify({
          sessionId,
          message: {
            actionType: "guardrail",
            prompt: userInput,
            newState: "resume"
          }
        })
      });

      attempts++;
      continue;
    }

    throw new Error("Unexpected result type");
  }

  throw new Error("Maximum guardrail attempts exceeded");
}

Related:

Debugging Checklist

When encountering issues:

Getting Help

If you’re still experiencing issues:

Documentation: Review relevant API docs
Status Page: Check status.webrun.ai
Support: Email support@webrun.ai with:
- Error code and full error response
- Session ID and task ID
- Task description
- Timestamp of occurrence
- Steps to reproduce

Common Issues

Solutions for frequent problems

FAQs

Answers to common questions

Best Practices

Guidelines for optimal usage

API Reference

Complete endpoint documentation

Getting Started

Concepts

Usage Guides

Integrations

Environments

API Reference

Capabilities

Troubleshooting

Documentation Index

​Quick Fixes Summary

​Error Response Format

​HTTP Status Codes

​Authentication Errors

​INVALID_API_KEY

​API_KEY_EXPIRED

​UNAUTHORIZED

​Session Errors

​SESSION_NOT_FOUND

​SESSION_EXPIRED

​SESSION_LIMIT_REACHED

​INSTANCE_UNAVAILABLE

​Task Execution Errors

​TASK_NOT_FOUND

​TASK_ALREADY_RUNNING

​TASK_TIMEOUT

​INVALID_TASK_DETAILS

​Browser & Navigation Errors

​NAVIGATION_TIMEOUT

​PAGE_CRASH

​ELEMENT_NOT_FOUND

​Rate Limiting & Network Errors

​RATE_LIMIT_EXCEEDED

​Billing & Payment Errors

​INSUFFICIENT_BALANCE

​PAYMENT_FAILED

​Validation Errors

​INVALID_PARAMETER

​MISSING_REQUIRED_FIELD

​MCP-Specific Errors

​MCP_SESSION_NOT_FOUND

​MCP_METHOD_NOT_FOUND

​MCP_INVALID_REQUEST

​Error Handling Best Practices

​Complete Error Handling Example

​Handling Guardrails

​Debugging Checklist

​Getting Help

​Related Resources

Common Issues

FAQs

Best Practices

API Reference

Quick Fixes Summary

Error Response Format

HTTP Status Codes

Authentication Errors

INVALID_API_KEY

API_KEY_EXPIRED

UNAUTHORIZED

Session Errors

SESSION_NOT_FOUND

SESSION_EXPIRED

SESSION_LIMIT_REACHED

INSTANCE_UNAVAILABLE

Task Execution Errors

TASK_NOT_FOUND

TASK_ALREADY_RUNNING

TASK_TIMEOUT

INVALID_TASK_DETAILS

Browser & Navigation Errors

NAVIGATION_TIMEOUT

PAGE_CRASH

ELEMENT_NOT_FOUND

Rate Limiting & Network Errors

RATE_LIMIT_EXCEEDED

Billing & Payment Errors

INSUFFICIENT_BALANCE

PAYMENT_FAILED

Validation Errors

INVALID_PARAMETER

MISSING_REQUIRED_FIELD

MCP-Specific Errors

MCP_SESSION_NOT_FOUND

MCP_METHOD_NOT_FOUND

MCP_INVALID_REQUEST

Error Handling Best Practices

Complete Error Handling Example

Handling Guardrails

Debugging Checklist

Getting Help

Related Resources