响应处理

本页说明如何判断响应形态、解密和读取结果，以及超时与重试规则。

响应形态

不要依据 HTTP 状态码判断结果：网关拒绝和业务响应的状态码都是 200，业务服务链路异常时是 400 或 5xx。HTTP 库遇到 4xx / 5xx 抛异常时，也必须取出响应体再按下表处理。

响应体必须按原始字节读取、按 UTF-8 解码成文本，不得交给 HTTP 库按 Content-Type 自动解析 JSON：密文响应的 Content-Type 同样是 application/json;charset=UTF-8。响应体有两种形态，先判断再处理：

形态	判断方法	处理方式
密文	响应体不以 `{` 开头	请求已通过网关校验。按下面三步解密，得到统一响应 JSON
明文 JSON	响应体以 `{` 开头	不要解密，读取 `code` 判断成败（`0` 为成功，`data` 即业务数据）；提示信息在 `message` 字段，没有 `message` 时读 `msg`。通常是请求被网关拒绝、请求体为空、业务服务链路异常或系统异常；但未配置 aesKey 的实例，或响应加密环节异常时，正常的业务响应也会以明文返回

网关和业务服务给出的响应只有这两种形态，Base64 字母表里没有 {，不会混淆。HTTP 状态码不是 200 且响应体不以 { 开头（如前置负载均衡返回的 HTML 错误页或空响应体）时，按系统异常处理，不要解密，按本页「超时与重试」处理。

解密

响应文本就是 Base64 文本，形式同请求与加密「加密规则」的「输出」，不带引号和首尾空白。必须用标准（非 URL-safe）Base64 解码器，遇到字母表外字符应报错（RFC 4648 §3.3）。

用与请求相同的密钥和 IV 做 AES-256-CBC 解密，去掉 PKCS#7 填充。

得到的字节按 UTF-8 解码，即统一响应 JSON（RFC 8259）。

解密向量见示例与自测第五步。

统一响应

字段	类型	说明
`code`	number	`0` 表示成功，其他值表示失败
`msg`	string	失败原因；成功时为 `null`
`data`	object / array	业务数据，结构见各接口的「返回响应」；失败时为 `null`
`ok`	boolean	是否成功，等价于 `code == 0`

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

{"code": 2010, "msg": "订单不存在", "data": null, "ok": false}

code=0 只表示请求被受理并给出了结果。申请退单、取消预约还要看 data 里的业务状态（refundStatus、cancelStatus）。

网关直接返回的明文错误，HTTP 状态码为 200，提示信息的字段名是 message（不是 msg）：

{"code": 1037, "data": null, "message": "数据验证失败"}

业务服务链路异常时，HTTP 状态码为 400 或 5xx，响应体为明文：

{"msg": "Bad Request", "code": 400}

链路 ID

链路 ID：每次响应的响应头都带 trace_id（如 trace_id: 85b0e0e63d3147e8），成功、失败都有。请在调用日志中记录该值；反馈问题时连同接口地址、请求时间一并提供，便于排查。

超时与重试

申请退单、取消预约会同步调用多个内部服务，读超时请设为 30 秒以上。

这两个接口按订单号和订单当前状态幂等：超时、网络异常、返回 HTTP 400 / 500 或 2312 后，用相同参数重试即可，不会重复办理。已办理的返回 code=0 和办理结果（code=0 不代表本次新办理）；结果还没确认或正在同步时返回 2312，一般 2 分钟内消失，持续超过 2 分钟请停止重试，改用「查询退单」或「查询订单列表」（subOrderFlag=1）查看。两次调用之间订单状态变了（上一笔退单被关闭、取消预约后又重新预约），再调会按新请求办理。

查询接口不改数据，可以直接重试。

响应大小

加密后的响应超过约 256 KiB（解密后的统一响应 JSON 约 190 KiB 以上）时，网关无法返回结果，会得到明文错误。分页查询请控制每页条数（带出的子订单也计入响应），单次结果过大时缩小查询范围。

响应形态#

解密#

统一响应#

链路 ID#

超时与重试#

响应大小#

响应形态

解密

统一响应

链路 ID

超时与重试

响应大小