Fetch the complete documentation index at: https://api-doc.myhostex.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# 错误码

# 错误码

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

```json
{
  "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` 不匹配。               | 重新签发 / 重新授权。详见 [鉴权](https://api-doc.myhostex.com/reference/authentication)。     |
| `403`                 | 无权访问    | 已鉴权但资源不属于你（例如访问别的房东账号的会话）。                                                                            | 停止访问；该资源不属于当前用户。                                                                |
| `404`                 | 资源不存在   | 资源 ID 错误，或者路径拼错。                                                                                      | 校对 ID；不要重试。                                                                     |
| `409`                 | 冲突      | 动作会产生重复（例如创建同名标签）。                                                                                    | 协调状态后再试，不要重复提交相同请求。                                                             |
| `422`                 | 参数校验失败  | Body 解析通过但业务规则不通过（例如 `note` 太长、`start_date` 晚于 `end_date`、`id_required` 不在枚举内）。`error_msg` 会带上具体出错字段。 | 修正请求参数；不要重试。                                                                    |
| `420`                 | 账号 / 订阅 | 房东账号问题：订阅过期、基础版调用 Pro 功能、账号被封禁。                                                                       | **不要重试。** 把信息透传给房东，让他到后台处理。                                                     |
| `429`                 | 限流      | 账号级、接口级、线程级或单 token 限流命中，也可能是 OAuth 暴力破解保护。                                                           | 按 `Retry-After` 退避。详见 [限流](https://api-doc.myhostex.com/reference/rate-limits)。 |
| `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 层，见 [限流](https://api-doc.myhostex.com/reference/rate-limits)），不是第 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`

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 实际的行为。