API Reference

错误码

错误码

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

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

错误码参考

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

error_code类型触发场景应对方式
0成功请求成功—
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 层，见 限流），不是 Token 级。请把消息发送分散到不同会话，或降低单线程内自动回复频率。

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

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

所有调用都返回 420

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

DELETE /reservation_tags/{id} 返回 404

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

OAuth /oauth/authorizations 返回 429

OAuth 暴力破解保护：同一个 client_id 在 10 分钟内累计 10 次 client_secret / code_verifier 校验失败，后续请求会被拒绝。请确保你的刷新流程有去重机制（每个 Token 同时只跑一个刷新请求）。

提工单时该带什么

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

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

Updated 19 days ago

Updated 19 days ago