限流与错误

每个 HTTP API 响应都带 ret_code。HTTP 状态码不是事实来源 —— 不论传输层是什么， ret_code: 100 才表示业务成功。先看 ret_code。

返回码

ret_code	含义	客户端建议做法
100	成功	直接使用 exp_data / data。
101	无权限	检查 X-Ak 是否属于该项目，且 key 处于 Active 状态。详见 API 密钥。
102	限流	触发了限流或配额上限，按下面的退避策略重试。
103	缺少 project ID	请求体里 project_id 缺失或为空。
104	服务端错误	视作瞬时错误，按退避重试。
105	服务端错误	视作瞬时错误，按退避重试。
0	未知	视作瞬时错误，先按退避重试一次再上报错误。

msg 字段在有可读字符串时给出，仅作辅助提示，不要按机器格式解析。

设计重试

102、104、105、0 重试是安全的（接口幂等）。建议指数退避：

第 1 次：立刻
第 2 次：等 250 ms
第 3 次：等 1 s
第 4 次：等 4 s
失败

总重试预算请按调用方愿意付出的超时时间封顶。HTTP API 服务的是分组，不是数据写入路径， 超过期限请落到默认值，不要继续阻塞用户，详见 默认值与回退。

101、103 不要重试 —— 这是调用方配置错误（key 错、project_id 缺失），先修请求。

限流响应

ret_code: 102 是平台对调用方"现在被限流"的信号。当前不返回限流相关 header （没有 X-RateLimit-Remaining、没有 Retry-After），按上面的退避策略处理即可。

如果稳态流量持续触发 102，说明已经触及项目级流量上限，请联系支持评估是否调整限额。

传输层错误

应用层以下的错误都视作瞬时错误，用上面同样的退避策略：

• connect / dns 失败；
• TLS 握手失败；
• 没有可解析 JSON 体的 5xx。

对于没有 JSON 体的 4xx，记录后停止 —— 平台没看到一个值得处理的请求。

幂等性

/abc/get_experiments 与 /abc/get_feature_flags 是幂等的读接口。重试不会改变分组；只在最终 成功时让平台再记一次曝光。如果你担心重试期间的曝光重复：

• 把退避做得更激进，避免同一 unit_id 在短时间内产生大量曝光；
• 批处理任务在调用点加一层幂等门；
• 在线流量接受一点重复 —— 引擎会在曝光窗口内做去重。

一个完整的例子

http POST openapi.abetterchoice.ai/abc/get_experiments \
  X-Ak:$ak X-Et:$et X-Es:$sig \
  project_id=6666 unit_id=user_id_1
# {"ret_code":102,"msg":"traffic limit","exp_data":{}}

# 等 1 秒，重试
sleep 1
http POST openapi.abetterchoice.ai/abc/get_experiments ...
# {"ret_code":100,...}