限流

百居易在三层做限流，避免单一调用方影响整体稳定性。命中后会返回 HTTP 200，响应体里 error_code: 429，响应头里 Retry-After（秒）。

第 1 层 —— Token 级（用户级）

按 Access Token 维度，覆盖 v3 所有接口：

四个窗口同时校验——任意一个被破，整体即触发 429。

第 2 层 —— Token + 接口级

按 (Access Token, 请求路径) 维度限流：

横线表示该窗口不限制（但用户级限流仍然生效）。

第 3 层 —— POST /conversations/{id} 线程级限流

向房客发消息按 会话维度 限流（与 Access Token 独立），因为 OTA 渠道侧通常对消息接口有严格限流，百居易必须保护渠道账号不被封禁：

五个窗口同时校验。请据此设计你的消息模板和 HostGPT 自动回复频率。

命中限流时的响应

HTTP/1.1 200 OK
Retry-After: 60
X-RateLimit-Scope: user            # 或 "endpoint"
X-RateLimit-Window: 1m
X-RateLimit-Reason: user rate limit exceeded: 1200 requests per 1m

{"error_code":429,"error_msg":"Too Many Attempts.","request_id":"RT..."}

第 3 层（消息线程级）会在响应体里明确告知何时可以重试：

{"error_code":429,"error_msg":"Too many requests. Try again in 60 seconds.","request_id":"RT..."}

如何避免被限流

1. 请求带上有意义的 User-Agent——例如 MyCleaningApp/1.2.3 ([email protected])。这有助于百居易识别合法集成方、绕过 IP 层防爬虫，遇到问题时也方便值班同事联系到你。
2. 字典类接口积极缓存。 GET /custom_channels、GET /income_items、GET /expense_items、GET /income_methods、GET /expense_methods、GET /tags、GET /groups 变更很少，最多 1 小时拉一次，不要每次创建订单都重新拉一遍。
3. 能批量就批量。 POST /listings/prices 支持数组——按 "渠道房源 × 日期段" 一次提交，不要每天一调。
4. 重试时加抖动。 收到 429 后按 Retry-After 指数退避，再叠加 ±25% 随机抖动，避免下一个窗口开闸瞬间的踩踏。
5. 不要轮询 Webhook 能告诉你的事情。 订阅 Webhook 比每分钟轮询 GET /reservations 高效得多，事件延迟 < 5s。
6. 写后查用 id 过滤。 写完一条记录后用 GET /reservations?id=… 重新拉单条，比重新拉整页列表轻得多。

不属于限流的 "类 429"