API 集成约定

数值与时间复制标题链接

金额以最小货币单位的整数字符串传输，并附币种。USD 的 "1250" 表示 12.50 美元。流量是字节整数字符串；不要转换为浮点数再计算，使用 bigint 或任意精度整数。时间戳带时区，只在展示时转换到用户或业务时区。

写入与版本复制标题链接

为一次业务意图生成并保存 Idempotency-Key。响应丢失时以同键、同请求体重试；不要为同一意图反复创建新键。同键不同请求体会冲突，未知付款结果也不能用第二笔付款解决。

带版本的资源按端点要求发送 If-Match。冲突时重新读取、比较并由用户确认，不能盲目覆盖。具体请求头与限制见端点参考。

错误与重试复制标题链接

错误使用 application/problem+json，按稳定的 code 分支，不按面向人的 title 或 detail 判断。保存 request id 供运营排查；5xx 不公开内部异常。

429 遵守 Retry-After；网络错误和 5xx 使用有上限的指数退避与抖动，并保持原幂等键。401 需要恢复会话或凭据，403 表示权限或状态拒绝。客户越权可能返回 404，以隐藏他人资源是否存在。其他 4xx 应修复输入或状态，不循环重试。

鉴权与数据保护复制标题链接

用户只访问自己的资源。后台需要相应权限、本会话 MFA，某些操作还要求近期再验证。Cookie 认证遵守站点 Origin 策略和端点请求头要求。节点使用独立服务器令牌，不复用员工或客户凭据。

限制响应大小和超时，避免将凭据放入 URL、日志或公开错误。私有文件只通过授权下载；订阅 URL 本身也是凭据，应限制分享和日志记录。