错误码
错误有三种形式：身份验证错误以 HTTP 401 返回；业务规则错误在 HTTP 200 响应中以 success: false 返回；预订推送错误位于 BookingPushRS.Error 中。本页列出了所有错误码。
身份验证错误#
| HTTP | 响应 | 原因 |
|---|---|---|
| 401 | {"success": false, "error": "Authentication required"} | token 缺失、无法识别，或 Bearer 格式错误。 |
| 200 | message: partner_is_not_found | 登录：密钥对不匹配。 |
| 200 | message: hotel_is_not_found | 登录：找不到与 hotelSeoUrl 对应的酒店。 |
| 200 | message: hotel_permission_is_not_found | 登录：合作伙伴未获得该酒店的授权。 |
message 代码#
snake_case 格式的文本代码，与 success: false 一同返回。
| message | 端点 | 说明 |
|---|---|---|
hotel_id_is_not_found | 大多数端点 | 未发送 hotelID。 |
start_date_is_not_found / end_date_is_not_found | 房态 | 缺少日期参数。 |
online_cupon_is_not_found | 优惠券 | 优惠码不存在、已停用、已过期或不可用。 |
mail_host_is_not_found | 邮件设置 | 在线渠道未配置 SMTP。 |
hotel_company_info_could_not_found | 虚拟 POS 信息 | 酒店未配置支付服务商。 |
bank_info_is_not_found | 支付（方式 3） | 没有为在线销售启用的银行账户。 |
required_input_info_not_submitted | 支付（方式 10） | 缺少必填字段；errors[] 列出了具体字段。 |
country_info_sent_incorrectly | 支付（方式 10） | countryID 不在国家列表中。 |
there_is_missing_info_in_the_shopping_cart | 支付（方式 10） | 某个购物车项缺少 id、name、piece 或 price；errors[] 会指明是哪一项。 |
房型列表错误码#
房型列表（POST /external/online/roomType）返回数字型的 errorCode 和可读的 errorMessage。消息文本会根据 language 参数翻译，因此请在代码中以 errorCode 为判断依据。
| errorCode | 含义 | 处理方式 |
|---|---|---|
10001 | 未找到酒店 | 检查 hotelID。 |
10002 | 缺少参数（hotelID、startDate、endDate、adultCount） | 发送必填字段。 |
10003 | 酒店未开放在线销售 | 酒店需在后台启用在线渠道。 |
10004 | 没有向渠道开放的房型 | 酒店需开放房型的在线销售。 |
10022 | 参数无效 | 入住日期为今天或之后，退房日期晚于入住日期，最多 30 晚，成人 1–40 人，儿童 0–10 人。 |
20001 | 成人可用房量不足 | 向客人推荐其他日期或入住人数。 |
20002 | 儿童可用房量不足 | 已没有可容纳儿童的房间。 |
20003 / 20004 | 成人和儿童可用房量均不足 | 总容量无法满足请求。 |
如果有可用房，但某个房型无法销售，则该房型的 roomCount 为 0，原因见 roomRestrictionMessage：closed_to_checkin、closed_to_checkout、passive_sales、minimum_stay、maximum_stay、closed_to_arrival、price_not_found。
预订推送错误#
此时 BookingPushRS 中没有 Success: true，而是带有 Error 字段：
{
"BookingPushRS": {
"Error": "Could not register.",
"BookingConfirmNumbers": [
{
"confirmTime": 1755500000,
"bookingID": 0,
"bookingType": "Book",
"HMS_ID": null
}
]
}
}| Error | 代码 | 原因 |
|---|---|---|
| No available data could be found. | 01 | 请求体为空或 JSON 无法解析；缺少 Bookings[0].hotelID。 |
| Hotel registration not found on HMS. | 02 | 酒店未接入在线渠道，或渠道已停用。 |
| Could not register. | — | 保存时出错（房型/餐食类型 ID 无效、日期不一致）。 |
| Failed to parse information. | — | 结构中缺少预期的字段。 |
重试建议#
- 401：重新登录一次，然后重试请求。
- 500 及网络错误：最多重试 3 次，间隔分别为 1 秒、2 秒、4 秒。重试预订推送时，请沿用相同的
ID；使用已存在编号的Book会更新该记录，而不会创建重复预订。 - success: false：不要重试；修正参数，或为客人提供其他选择。
- 提交支持工单时，请附上完整请求（机密信息和卡数据需脱敏）、响应和请求时间。