Business and HTTP error codes

Successful responses use code = 0; failed responses use code > 0. The HTTP status and business code are separate values. Use the endpoint, message and current state to distinguish errors that share a code.

Business error codes

code	Message / meaning
40003	missing host header
40004	host is not allowed
40005	host port is not allowed
40006	invalid origin
40007	origin is not allowed
40008	origin port is not allowed
40010	invalid browser path parameters
40011	Invalid browser profile start parameters or missing env_id
40012	Invalid browser profile stop parameters or missing env_id
40013	invalid browser list query
40014	invalid browser batch start request
40015	invalid browser batch stop request
40016	Invalid browser profile restart parameters or missing env_id
40017	invalid browser stop-all request
40018	invalid browser batch restart request
40019	invalid browser create request
40020	Invalid parameters for updating a browser profile or querying the group list
40021	invalid group path parameters
40022	invalid group create request
40023	invalid group update request
40024	invalid group browser move request
40025	Invalid parameters for deleting one or more browser profiles
40026	invalid browser permanent delete request
40030	invalid proxy list query
40031	invalid proxy path parameters
40032	invalid proxy create request
40033	invalid proxy host or IP protocol
40034	invalid proxy update request
40035	invalid proxy check request
40036	invalid proxy browser binding request
40040	invalid extension list query
40041	invalid extension path parameters
40042	invalid extension browser binding request
40050	invalid recycle bin list query
40051	invalid recycle bin restore request
40052	invalid recycle bin delete request
40060	Invalid browser kernel query or path parameters
40061	Invalid fingerprint option or font list query parameters
40062	invalid random WebGL option query
40063	invalid random profile font query
40070	invalid account list query
40071	invalid account path parameters
40072	invalid account create request
40073	Invalid account update parameters, including a missing platform_id when changing the account type
40074	invalid account platform list query
40075	invalid account platform create request
40101	missing api key
40102	empty api key
40103	invalid api key
40104	backend session unavailable
40105	backend permission denied
40301	operation is not permitted
40400	api endpoint not found
40401	browser environment not found
40402	group not found
40403	proxy not found
40404	extension not found
40405	recycled browser environment not found
40406	profile kernel option not found
40407	profile system option not found
40408	account not found
40409	account platform not found
40901	browser environment exceeds package limit
40902	browser kernel is unsupported on this platform
40903	browser environment is not active
40904	The operation is restricted because the browser profile uses pipe transport (close it and start it through Local API to obtain an external WebSocket endpoint), or because the default group cannot be deleted
40905	default group cannot be updated
40907	group still contains browsers
40911	group already exists
40912	proxy mode cannot be changed
40913	managed proxy cannot be updated
40914	managed proxy cannot be deleted
40915	browser environment package limit exceeded
40916	recycled browser environment is still active
40917	custom account platform already exists
40918	browser environment limit exceeded
40919	only one account per platform can be bound to a browser
40920	browser environment is still active
42201	failed to extract proxy endpoint from proxy API URL
42202	browser kernel, system and User-Agent are not compatible
42203	invalid proxy configuration
42204	invalid account configuration
50001	Local API encountered an internal error or its runtime status is unavailable
50002	active browser endpoint unavailable
50003	Failed to start or restart the browser profile
50004	active browser group unavailable
50005	browser environment did not stop
50201	Failed to load browser profiles or their details because the request failed, the returned data is invalid, or the processing limit was exceeded
50202	failed to load supported kernels
50203	Browser profile startup preparation failed, the backend rejected startup, or the returned data is invalid
50204	failed to open browser URL
50205	Failed to create the browser profile or the creation result is invalid
50206	Failed to update the browser profile or the update result is invalid
50207	Failed to delete browser profiles or move them to the recycle bin
50208	Failed to permanently delete browser profiles
50209	Failed to load the full browser profile configuration or the returned data is invalid
50210	A group operation or related browser profile lookup failed, the returned data is invalid, or the group list exceeds the processing limit
50211	Failed to create the group or retrieve the creation result
50212	failed to update group
50213	failed to delete group
50214	failed to move browsers to group
50215	default group unavailable
50220	Failed to load proxies, the returned data is invalid, or the proxy list exceeds the processing limit
50221	failed to create proxy
50222	failed to update proxy
50223	failed to delete proxy
50224	Failed to check the proxy, refresh its endpoint, or update its check status
50225	failed to bind proxy environments
50230	Failed to load extensions, the returned data is invalid, or the extension list exceeds the processing limit
50231	Failed to update browser profiles bound to the extension or retrieve the update result
50240	Failed to load the recycle bin, the returned data is invalid, or the list exceeds the processing limit
50241	failed to restore browser environments
50242	failed to permanently delete browser environments
50243	Failed to clear the recycle bin or load the browser profiles to be cleared
50250	Failed to load fingerprint options or the returned kernel, system, or User-Agent options are invalid
50251	Failed to load a random WebGL option or the returned data is invalid
50252	Failed to load the font list or the returned data is invalid
50253	Failed to load random fonts or the returned data is invalid
50260	Failed to load accounts or the returned data is invalid
50261	failed to create account
50262	failed to update account
50263	failed to delete account
50264	Failed to retrieve account details, including after creating or updating an account
50265	Failed to load account platforms or the returned data is invalid
50266	Failed to create the account platform or the returned data is invalid
50301	main client window is unavailable
50302	Local browser settings are unavailable or invalid
50303	browser kernel is not installed locally
50304	browser extension is not installed locally:
50305	The operation is temporarily unavailable because browser profile cache cleanup is in progress or the internal local server is unavailable
50306	failed to delete browser environment cache
50307	profile options are unavailable on this platform

Error response

Field	Type	Description
code	integer	Positive business error code.
message	string	Specific error details.
data	object | null	Additional error details, or null when no details are available.
request_id	string	Request trace ID, also in X-Request-Id.

Possible fields in data: env_id (string), env_ids (string[]), status (string), issues (object[]). Each validation issue has code (string), path (string[]) and message (string). The fields returned depend on the specific error.

Batch requests can return HTTP 200 / code = 0 while individual items fail. Inspect each item’s success and error. Item errors appear in data.items[].error; additional details, when present, belong to that error object. Runtime errors may also be passed through.

HTTP status codes

HTTP	Description
400	Invalid request or parameters
401	Missing or invalid API Key
403	Request forbidden by access or security rules
404	Resource or route not found
409	Operation conflicts with the current state
422	Request validation failed
500	Internal error
502	Upstream service error
503	Service unavailable