错误码

错误码

百居易 OpenAPI v3 所有响应都使用统一的信封格式:

{
  "request_id": "RT2026052115252141408b3",
  "error_code": 200,
  "error_msg": "Done.",
  "data": {}
}
  • 即使业务上失败,HTTP 状态码仍然是 200。 业务结果一律看响应体的 error_code,不要看 HTTP 状态。
  • error_code: 200 代表成功,任何非 200 的值都是失败。
  • data 是接口的返回结果;接口没有数据要返回时不含 data 字段。
  • error_msg 是一段简短的英文人类可读文本,不要用它做程序判断——程序判断请使用 error_code。
  • 提工单时务必带上 request_id,服务端日志按它检索。

错误码参考

错误码语义对齐 HTTP 标准状态码,方便客户端直接复用。

error_code类型触发场景应对方式
200成功请求成功—
400请求格式错误入参格式错、缺必填、参数冲突(例如 scope=entire 同时传了非空 property_ids)。修正请求参数;不要重试。
401鉴权失败Token 缺失、无效、已删除、scope 不足;OAuth 接口的 client_id / client_secret / code_verifier 不匹配。重新签发 / 重新授权。详见 鉴权。
403无权访问已鉴权但资源不属于你(例如访问别的房东账号的会话)。停止访问;该资源不属于当前用户。
404资源不存在资源 ID 错误,或者路径拼错。校对 ID;不要重试。
409冲突动作会产生重复(例如创建同名标签)。协调状态后再试,不要重复提交相同请求。
422参数校验失败Body 解析通过但业务规则不通过(例如 note 太长、start_date 晚于 end_date、id_required 不在枚举内)。error_msg 会带上具体出错字段。修正请求参数;不要重试。
420账号 / 订阅房东账号问题:订阅过期、基础版调用 Pro 功能、账号被封禁。不要重试。 把信息透传给房东,让他到后台处理。
429限流账号级、接口级、线程级或单 token 限流命中,也可能是 OAuth 暴力破解保护。按 Retry-After 退避。详见 限流。
500服务器错误百居易侧 Bug、部分故障、上游渠道超时。指数退避重试;如果仍然失败,带 request_id 提工单。
501未实现接口存在但该账号未启用(例如未配置公共客户端时调用动态 OAuth 注册)。提示用户,不要重试。
502 / 503 / 504上游错误百居易侧可达,但下游渠道(Airbnb / Booking.com 等)失败。可重试。仍然失败则提工单。

常见错误场景速查

第一次调用就 "Invalid access token"

  • 请求头拼错:应为 Hostex-Access-Token(中横线),不是 Hostex_Access_Token / Hostex-Access_Token。
  • Token 前后有空格,发送前请 trim。
  • Token 在百居易后台已删除或轮换。

"Not authorized for this action"

Token 是 只读 的。Scope 在 Token 创建时确定,无法事后修改——请在 OpenAPI 设置页新建可写 Token,并撤销旧的。

POST /conversations/{id} 返回 429,但没到 1200/分钟

你命中的是 线程级 消息限流(限流的第 3 层,见 限流),不是第 1 层的账号级配额。请把消息发送分散到不同会话,或降低单线程内自动回复频率。

创建订单标签 / 房间标签时返回 409

同名标签已存在(也可能是被软删除的,会自动恢复——可以先 GET /reservation_tags?keyword=… 排查)。同一账号内标签名必须唯一。

所有调用都返回 420

房东的订阅过期或被降级到基础版。Token 本身没问题,需要房东到后台续费 / 升级。集成方在服务端无法解决这个问题。

DELETE /reservation_tags/{id} 返回 404

该标签是系统 默认标签(is_default: true),不允许通过 API 删除。只能删除房东自建的标签。建议在 UI 上根据 is_default 字段隐藏 "删除" 按钮。

DELETE /reservations/{code} 返回 404

该接口只能取消手工创建的订单。渠道订单(Booking.com、Agoda、携程……)不在这个接口的可寻址范围内,会返回 404 并附 Only manually created reservations can be cancelled through this endpoint.——请到渠道侧取消。订单号前缀不是 5- 就说明这次调用不可能成功。

同一路由返回 This resource is no longer available. 则表示该订单号在你的账号下确实不存在。

两种都是 404:核对后停止,不要重试——2026-09-08 之前这种情况被报成 500,而我们对 500 的指引是重试。

OAuth /oauth/authorizations 返回 429

令牌交换按 client_id、grant_type 和请求 IP 分桶(IPv6 地址按 /64 归为同一来源),分别维护两类失败计数:

  • 凭据失败(未知客户端、client_secret 错误或 code_verifier 校验失败):已记录的失败计数大于 10 时拒绝请求。
  • 客户端认证通过后的无效或已用过的授权码、refresh token:独立计数,已记录的失败计数达到配置上限(默认 200)时拒绝请求,不占用凭据失败额度。

公共客户端(无 client_secret)另按 client_id 和请求 IP 统计不同的无效 refresh token 个数,达到配置上限(默认 30)时拒绝请求。同一个 refresh token 在一个窗口内重试只计一次。

每类计数均使用从该桶第一次失败起算的固定窗口:凭据失败为 600 秒(10 分钟),无效 grant 和公共客户端的这项计数默认为 600 秒。后续失败不会延长窗口,不同请求 IP 的失败不占用同一个桶。

以上计数超限均可能返回 429 Too many attempts.。请修正错误凭据,停止重试无效 grant;触发限流时退避。

refresh token 轮换默认有 60 秒宽限期。在此期间重复使用旧 refresh token,只要新令牌记录仍存在,就返回同一对新 access token、refresh token,expires_in 为剩余有效秒数。宽限期结束或新令牌记录已被撤销后,使用旧 refresh token 返回 400 Invalid refresh token.。仍建议每个 token 同时只跑一个刷新请求,并原子保存返回的令牌对。


提工单时该带什么

为了让值班同事能在一分钟内复现问题,请同时提供:

  1. 失败响应体里的 request_id。
  2. 失败的大致时间(UTC)。
  3. 调用的 HTTP method 和路径(路径不必脱敏,敏感数据只会在 body / header 里)。
  4. 使用的鉴权方式(Access Token 或 OAuth Bearer Token,不要把 Token 本身贴出来)。
  5. 期望的行为 vs 实际的行为。