返回码与排查

本页列出所有接口共用的返回码和排查方法。各接口特有的业务错误见该接口页的「业务错误」。

网关校验顺序

网关收到请求后依次做以下校验，任意一步不通过即返回对应错误，后面的步骤不再执行。同一个返回码在不同步骤含义不同，按提示信息区分：

顺序	校验内容	不通过时返回
1	`Content-Type` 是否为 `application/json`	`405` 无效的请求内容
2	请求体能否读取并解析为请求与加密规定的 JSON 报文（不超过 256 KiB）	`500` common.system.busy
3	`key` 是否存在	`1037` 无效的key
4	`key` 是否启用	`1031` 用户状态有误，请联系管理员
5	用该 key 的 `secret` 按「签名规则」重算签名，与 `sign` 比较	`1037` 数据验证失败
6	请求地址是否为已登记的接口	`405` 无效的请求信息
7	该应用实例是否已被授权此接口	`405` 用户权限不足
8	实例开启了 IP 白名单时，来源 IP 是否在白名单内	`1044` 请求的ip不在白名单当中
9	用 `aesKey` 解密 `body`	`1020` 无效的AES数据格式

全部通过后，网关把解密出的业务参数转给业务服务。来源 IP 取 X-Forwarded-For 的第一个地址。

例外：请求体为空时网关不做第 2–9 步，直接转给业务服务，业务服务不做任何业务处理，返回业务明文 1031「未获取到调用方身份，请求报文不能为空且须通过签名校验」。收到它时先检查 HTTP 组件是否真的发出了请求体。

返回码

层级说明：「网关明文」是以 { 开头的明文响应，提示字段为 message（HTTP 状态码 200）；「业务明文」同为明文，提示字段为 msg；「链路异常」的 HTTP 状态码为 400 或 5xx，提示字段为 msg；「业务密文」解密后提示字段为 msg，各接口页的「业务错误」列出了每条提示对应的返回码，业态服务（门票、演出、组品、酒店、商品、预售）给出的返回码原样透出。

层级	code	提示 / 含义	问题排查方向
网关明文	`1037`	无效的key	先检查是否发送了未加密的业务参数（直接复制了本站的业务参数示例）：请求体必须是 `key`、`timestamp`、`body`、`sign` 四个字段。其次检查 `key` 是否填错、是否用错环境
网关明文	`1037`	数据验证失败	签名不匹配，或缺少 `sign`，按下文「签名失败排查」检查。复制「线上报文（核对用，不能发送）」示例、只换了 `key` 也会返回这个错误
网关明文	`1031`	用户状态有误，请联系管理员	`key` 已被禁用，联系平台管理员
网关明文	`1044`	请求的ip不在白名单当中	来源 IP 未加入该实例的白名单
网关明文	`1020`	无效的AES数据格式	签名已通过，`body` 无法解密：不是用该实例 `aesKey` 加密的合法密文，或不是标准 Base64，见下文「签名失败排查」最后两段
网关明文	`405`	无效的请求内容	`Content-Type` 不是 `application/json`，或按表单提交
网关明文	`405`	无效的请求信息	请求地址不是已登记的接口，检查路径拼写
网关明文	`405`	用户权限不足	该实例未被授权此接口，联系平台管理员授权
网关明文	`500`	common.system.busy	请求体不是合法 JSON、超过 256 KiB、`timestamp` 带引号且含小数点 / 指数 / 空格，或网关内部异常
业务明文	`1031`	未获取到调用方身份，请求报文不能为空且须通过签名校验	请求体为空（网关不校验空请求体，见上文「网关校验顺序」的例外）。检查 HTTP 组件是否真的发出了请求体，按请求与加密发送完整的请求报文
链路异常	`400`	Bad Request	业务服务异常，不代表失败。申请退单、取消预约可直接用相同参数重试；查询接口可直接重试；持续出现请联系平台并提供 `trace_id`
业务密文	`0`	成功
业务密文	`1020`	参数错误	解密后的业务参数不是 JSON 对象（`msg` 为「业务参数格式有误，必须为JSON对象」）、日期格式不对、`subOrderFlag` 取值不对、分页参数超出范围、预约子订单与销售订单不匹配、`refundReason` / `cancelReason` 超过 256 个字符
业务密文	`1021`	参数不能为空	必填的订单号、景区编码、退单原因、取消原因没传；查询条件一个都没传
业务密文	`1031`	该应用实例无权调用本接口，请联系平台管理员	该应用实例无权调用本接口：请把接口地址告知平台管理员开通
业务密文	`2010`	订单不存在	订单号、预约子订单号不存在
业务密文	`2301`	退单实名制名单不一致	实名制订单可退出行人数量与退单数量对不上，需到运营平台人工处理
业务密文	`2309`	退单数量不足	订单已退完或已使用，没有可退数量
业务密文	`2310`	订单状态异常	子订单不能单独退、订单已锁定、订单没有预约 / 没有可取消的预约、预约已结束 / 待确认、该预约位已重新预约
业务密文	`2311`	规则设置不可退	按退改规则当前不可退
业务密文	`2312`	办理中	上一次请求还在办理或结果暂未确认、正在同步，或订单有退单 / 取消在处理。申请退单、取消预约用相同参数重试；持续超过 2 分钟停止重试，改用查询接口查看
业务密文	`2314`	订单已使用	商品订单已核销
业务密文	`2315`	退单手续费异常	扣除手续费后可退金额为 0，需到运营平台人工处理
业务密文	`405`	其他业务异常	没有专用返回码的业务拒绝，例如景区不存在
业务密文	`400` / `500`	系统异常	内部服务超时或异常，不代表失败。申请退单、取消预约可直接用相同参数重试

签名失败排查

返回 1037 数据验证失败 时，按顺序检查：

是否对密文签名。待签名串的第一段是加密后的 Base64 字符串，不是明文 JSON。

请求体里的 body 与参与签名的 body 是否是同一个字符串。常见问题是加密了两次得到两个不同的密文、Base64 编码器在末尾加了换行，或签名后又对 body 做了 URL 编码、换行、首尾加空格（见请求与加密的「Base64 变体与 URL 编码」）。

请求体里的 timestamp 是否为「timestamp 格式」规定的 JSON 整数，参与签名的是否就是这串数字：不能带引号、小数、科学计数法或前导零。

secret 是否与 key 属于同一个应用实例、同一个环境，前后是否混入了空格或换行。

拼接顺序是否为 body + timestamp + secret，中间是否多了分隔符。

是否直接对拼接串做 MD5（不是 HMAC-MD5），输入是否按 UTF-8 取字节，输出是否为 32 个十六进制字符（不是 16 个，也不是 Base64）。

用示例与自测的演示数据和自测判据核对自己的实现。

返回 1020 无效的AES数据格式 时，说明签名已经通过、body 无法解密。检查密钥是否直接取 aesKey 的 UTF-8 字节（不要做 Hex 解码）、IV 是否为密钥前 16 字节（不是随机 IV）、模式是否为 CBC、body 是否为标准 Base64（见请求与加密的「Base64 变体与 URL 编码」）。

解密后返回 1020 业务参数格式有误，必须为JSON对象 时，加密和签名都已正确，问题在明文本身，按请求与加密「加密规则」的「明文」行和其后的说明检查。请求成功但中文内容乱码时，明文没有按 UTF-8 编码。

常见陷阱

timestamp 用了秒（10 位数字）。必须是毫秒（13 位数字）。

timestamp 写成了字符串，或签名用的数字串与请求体里的不一致。

用了 URL-safe Base64（-、_），或 Base64 编码器按行折返、末尾加了换行。

多数 MD5 库输出小写十六进制，要转成大写：本协议要求 sign 必须为大写。

把接口页的「业务参数（加密前）」示例直接发出（返回 1037 无效的key），或复制「线上报文（核对用，不能发送）」示例只换了 key（返回 1037 数据验证失败）。

让 HTTP 库按 Content-Type 自动把响应解析成 JSON：密文响应不是 JSON，要先按响应处理判断形态。

2026-11-12 的返回码变化

申请退单、取消预约按订单号和订单当前状态幂等，重复调用返回已有结果和 code=0：

申请退单：平台客服办理的整单退单在处理中或已完成时，再次调用不再返回 2309、2310、2312 或 405。

取消预约：指定的预约已取消（不论由谁取消），或取消全部时已没有待取消的预约，不再返回 2310。

结果暂未确认时，原来的 405「…结果未知…」改为 2312「…结果暂未确认…，请稍后用相同参数重试」；新增 2312 提示「上一次退单请求结果暂未确认…」「上一次退单已受理，结果正在同步…」「该订单有平台客服办理的退单正在处理中，请等它办结后再申请」「上一次取消预约请求结果暂未确认…」「该预约正在取消中，请稍后再试」。

取消预约：从未预约的预售券返回 2310「该订单没有预约，不能取消预约」。

业务返回码 1031 的提示语改为「该应用实例无权调用本接口，请联系平台管理员」；请求体为空时返回明文 1031「未获取到调用方身份，请求报文不能为空且须通过签名校验」。

提示语中订单的量词统一为「笔」，如「orderNo 与 outOrderNo 不是同一笔订单」。

网关校验顺序#

返回码#

签名失败排查#

常见陷阱#

2026-11-12 的返回码变化#

网关校验顺序

返回码

签名失败排查

常见陷阱

2026-11-12 的返回码变化