API 参考
错误、幂等与限流
按安全错误信封、幂等冲突、配额和挑战语义恢复，不猜测写入结果。
错误、幂等与限流
错误包含稳定机器码、安全文案和请求关联编号，禁止把自然语言当协议解析。写请求超时代表结果未知，不能直接当失败重发；必须先按幂等键查询事实。
| HTTP | 语义 | 客户端动作 |
|---|---|---|
400 / 422 | 请求或领域校验失败 | 修正字段，原样请求不得重试。 |
401 | 身份缺失、过期或已撤销 | 安全重新授权，不能放宽 CORS。 |
403 | Scope、角色、店铺、市场、同意或能力拒绝 | 停止操作并获取合法授权。 |
404 | 资源隐藏或不存在 | 不得枚举 ID。 |
409 / 412 | 幂等或乐观版本冲突 | 回读权威资源并协调。 |
429 | 限流或风险挑战 | 遵守 Retry-After，仅在服务端要求时完成挑战。 |
5xx | 服务不可用或结果未知 | 保留意图，退避后先对账。 |
限流按应用、安装、租户/店铺、路由和风险等级共同计算，不能只按 IP。Turnstile 当前为规划/未启用；未来即使通过 Siteverify，也只证明一次 bot challenge 结果。cf_clearance 不是登录态，不能绕过 OAuth scope、租户归属、配额或敏感操作 step-up。