Guides

Error Handling

All BrowseFleet API errors return a JSON body with an error field describing what went wrong.

Error Response Format

json

{
  "error": "Human-readable error message"
}

Status	Meaning	When It Happens
200	OK	Request succeeded
201	Created	Session or profile created successfully
400	Bad Request	Missing required parameter (e.g., url, task, actions)
401	Unauthorized	Missing or invalid API key
404	Not Found	Session, profile, or file not found
429	Too Many Requests	Maximum concurrent sessions reached
500	Internal Server Error	Browser crashed, navigation failed, or unexpected server error
501	Not Implemented	Feature not configured (e.g., CAPTCHA solving without CAPTCHA_API_KEY)
503	Service Unavailable	Stripe not configured (billing endpoints only)

400"url is required"

The scrape, screenshot, or pdf endpoint was called without a url field in the JSON body.

400"actions array is required"

The Computer API was called without an actions array, or the array was empty.

400"task is required"

The agent endpoint was called without a task field.

400"name is required"

Create profile was called without a name field.

429"Maximum concurrent sessions reached"

You have hit the MAX_CONCURRENT_SESSIONS limit. Release existing sessions before creating new ones.

404"Session not found"

The session ID does not exist, or the session has already been released or expired.

500"Navigation failed: net::ERR_NAME_NOT_RESOLVED"

The URL could not be resolved. Check that the URL is valid and the DNS name exists.

500"Navigation timeout of 30000 ms exceeded"

The page took longer than the timeout to load. Increase the timeout parameter or check if the site is accessible.

501"CAPTCHA solving not configured. Set CAPTCHA_API_KEY."

CAPTCHA solving was requested but no 2captcha API key is configured on the server.