API errors & troubleshooting

Local API requires Pro membership and a running client. Use the port and api-key from the API screen.

Response shape

Success: { "success": true, "data": { ... } }
Failure: { "success": false, "error": "..." }

Many failures still return HTTP 200—always check success.

Code	Meaning	Examples
`200`	Handled	OK or `success: false` in body
`400`	Bad request	Missing `id`, `Invalid id format`
`401`	Unauthorized	Bad/missing `api-key`; cloud sync not signed in
`403`	Forbidden	Cloud sync without Pro
`404`	Not found	Unknown profile/group id
`429`	Rate limited	Write queue full
`500`	Server error	Usually `error.message` from client

Error	HTTP	Fix
`Unauthorized: Invalid API key`	401	Copy fresh key from API
Connection refused	—	Start client; verify port
`请先登录后再进行云同步`	401	Sign in to the client
`仅限会员使用云同步功能`	403	Subscribe to Pro

Error	Meaning
`Missing required parameter: id`	Body missing `id`
`Missing required parameter: id, name, or remark.`	`launchBrowser` needs one identifier
`Missing required parameter: cookies`	Cookie update
`Missing or invalid parameter: accounts (must be an array)`	Platform accounts API
`Invalid id format`	`id` not a valid integer

Pattern	Meaning
`browser(id: N) not found`	Profile missing
`Browser with id N not found`	Same (variant wording)
`group(id: N) not found`	Group missing
`Browser data directory not found for id: N`	Data dir deleted
`Browser list is empty or not found.`	No profiles

Error	Action
`browser(id: N) is running`	Use returned `debuggingPort` or stop first
`No browser found with …`	Fix id/name/remark via `getBrowserList`
`Multiple browsers found with …`	Use unique `id`
`No browser data found for worker ID: N`	Restore backup or recreate
`Failed to parse proxy from API response`	Fix proxy extract URL format
`Failed to fetch proxy from API: …`	Network/auth on proxy API
`Browser process closed before DevTools port was detected.`	Kernel/proxy/AV issue
`Failed to detect DevTools port for worker N…`	Close conflicting Chromium

Error	HTTP
`Too many concurrent write requests, please retry later`	429

INFO

Exact strings follow the installed client—see Apifox after upgrades.