Responses and errors

Response envelope

Every endpoint uses { code, msg, data } as its response envelope. msg comes from the backend and can be ok or 成功 (success) on success, so do not use it to decide the outcome.

Success

{ "code": 0, "msg": "ok", "data": {} }

Service endpoint success

{ "code": 0, "msg": "成功", "data": {}, "contextId": "a3f5c2e1..." }

contextId appears only in successful responses from service endpoints and can be passed as X-Nex-Service-Context in later requests.

Business error

{ "code": 1, "msg": "windowId is required" }

Authentication failure · HTTP 401

{ "code": 401, "msg": "Authorization Bearer API key is invalid", "data": null }

Two kinds of code

Forwarded and local business endpoints return a numeric code; /automation/* returns a string code on failure (such as SESSION_NOT_FOUND) together with a non-200 HTTP status. Service endpoints also return a string code, SESSION_CONTEXT_CHANGED, when the sign-in or team has changed. Handle each type separately when parsing.

Pagination envelope

For /account/list, the /proxy/* lists, /browser/list, and the record lists of service endpoints, data is a common pagination structure with the records in data.data:

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 10,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": []
  }
}

count is the total number of matches, size is the page size (echoes the request), page is the current page (echoes the request), total is the number of pages, and data holds the records on the current page.

Batch result rows

Batch endpoints such as window creation, proxy binding, group moves, and fillable accounts return success and error per row. A failed row that carries a registered error code also has code (such as WINDOW_RUNNING_PROXY_LOCKED) and an optional params; error is always in Chinese and prefers the server's original text. When every row fails, the endpoint returns code: 1 and msg joins the failure reasons with newlines.

Status and error codes

The local layer uses non-200 status codes only for authentication failures, missing routes, and automation errors; everything else is HTTP 200 plus a business code.

Scenario	HTTP	code	Details
Success	200	0	Business data is in data
Local business error	200	1	Parameter validation failed or every row of a batch failed; the response may have no data field
Service parameter or context validation failure	200	-1100	Invalid parameters, no team selected, or an identical resource operation still in progress; stock and balance errors come from the server
Sign-in or team changed	200	SESSION_CONTEXT_CHANGED	The X-Nex-Service-Context of a service request does not match the current state, or it changed during execution
Server business error	200	Negative	Passed through unchanged, such as -1005 permission denied, -1208 insufficient balance, -3004 number already received an SMS
Invalid or missing key	401	401	Authorization Bearer API key is invalid
Route not found	404	—	Returns plain text Not Found, not JSON
Automation parameter error	400	INVALID_ARGUMENT	Missing field or wrong type; domain errors with a registered error code also fall here, with msg in Chinese
Action not allowed	400	ACTION_NOT_ALLOWED	Invalid action name, or the evaluate / runCode policy is off
Window state not met	400	WINDOW_NOT_FOUND · WINDOW_NOT_RUNNING	The window does not exist, or it is not running and startIfNeeded was not passed; an unavailable vault session also returns the latter
Client ID missing or not authorized	403	UNAUTHORIZED	X-Nex-Client-Id is missing or malformed, or the session's account and team context has changed
Session or tab not found	404	SESSION_NOT_FOUND · PAGE_NOT_FOUND	Invalid ID, or the session has been released
Action timeout	408	ACTION_TIMEOUT	The action or session timeout was exceeded

Charging requests with an unclear outcome

If a purchase, renewal, pull, or CAPTCHA task submission times out, loses its connection, or returns a non-zero code, that does not prove nothing was charged. Automation first checks the matching record endpoint and /billing/trades; stop that flow without resubmitting if acceptance or charging cannot be established. Only confirmed business failure or an SMS/email receiving timeout with a known original payment outcome permits replacement within interactive recovery's default 3 attempts including the first, without asking whether to continue. Default waits are 120 seconds for SMS and 180 seconds for email; one failed query is not a receiving timeout.

-1208 or insufficient_balance means insufficient balance and stops subsequent spending and quota consumption in the task and its subagents. The built-in Agent displays "Insufficient account balance. Paid operations have stopped. Top up before continuing." without requesting another proceed or top-up confirmation.