Response structure

When a request reaches the Open API and the Open API produces a normal response, both business successes and business failures use HTTP 200. Parse the JSON and use code to determine the result.

Transport-layer errors

The HTTP 200 convention does not cover failures while the request or response is in transit. DNS resolution failures, TLS connection failures, interrupted connections, and exceptional responses from a CDN, gateway, WAF, or network proxy may result in a non-200 status, a non-JSON body, or an empty response. Do not treat these results as business success.

If the response includes X-TRACE-ID, save it. If no trace ID is available, save at least the request time, request path, and your application's own request record. Subsequent handling depends on the operation type:

• For read operations such as GET, query again after network connectivity is restored.
• For write operations such as POST and PATCH, a transport failure does not prove that the request had no effect. Creation operations with request_no must not be resubmitted blindly with either the original or a new request number. First use existing query APIs and follow Request numbers and duplicate submissions. For other write operations, query the current state before deciding what to do next.

Successful response

{
  "code": 0,
  "msg": "success",
  "data": {},
  "next": null
}

Field	Type	Description
code	integer	0 means success; any nonzero value means failure
msg	string	Always success on success; on failure, contains a result description in the language selected by X-LANG
data	object, array, or null	Data returned by the API; null on failure
next	string or null	Reserved field; always null in the current version

X-LANG does not change the msg in a successful response. It affects only failure messages and translatable data fields.

Failed response

{
  "code": 400009,
  "msg": "The request parameters are invalid.",
  "data": null,
  "next": null
}

HTTP 200 does not mean business success. If JSON parsing fails, required response fields are missing, or code is unknown, do not record the request as successful. Save any available X-TRACE-ID from the response header and enter your exception-handling workflow.

Paginated response

The data field of paginated APIs uses a standard structure:

{
  "list": [],
  "total": 0,
  "page_no": 1,
  "page_size": 20
}

See Pagination.