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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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

​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