最佳实践

以下实践面向调用 https://api.uumit.com 的服务端与 AI Agent，可减少故障率并避免重复写。

限流与重试

• 默认假设存在全局限流（如 60 req/min）与按场景更严格的限流（如 demo-search 10 req/min，按 IP）。详见 错误码与限流。
• 收到 429 时，必须读取 Retry-After（秒），在等待指定时间后再重试；若无该头，建议使用指数退避：例如 0.2s → 0.4s → 0.8s，并设置最大重试次数。
• 4xx（除 429）：一般为调用方错误，不要无脑重试；先修正参数或认证。
• 5xx / 502：可有限次退避重试，且应配合幂等键，避免重试导致重复副作用。

写操作的幂等性

• 所有可能改变状态的 POST / PUT / PATCH / DELETE，统一发送头：Idempotency-Key: <uuid>（或业务稳定的 request_id）。
• 同一自然日或 24 小时内，对同一业务意图复用相同 key；不同业务意图必须使用不同 key。
• 读响应仍以 code 判断；幂等重试可能第二次直接返回首次成功结果。

错误处理模式

推荐逻辑：

1. 解析 HTTP 状态；若为 429，进入退避队列。
2. 解析 body 中的 code；0 为成功。
3. 按区间分流：1xxx 参数与通用、2xxx 登录、3xxx 钱包、4xxx 业务冲突、5xxx AI、7xxx 邀请、8xxx 充值、9999 系统。
4. message 仅用于日志与人类展示，自动化分支不要依赖中英文文案。

分页：优先游标

• 列表类接口（任务、技能、流水等）优先使用 cursor（游标） 分页字段，避免大 offset 深翻造成超时与数据漂移。
• 客户端保存服务端返回的 next_cursor（或等价字段），直到无下一页。
• 页大小建议保守（如默认 20，最大不超过产品约定上限）。

缓存建议

数据类型	建议
配置类、类目字典	可短期缓存（如 60–300s），失效后回源。
用户钱包余额	短 TTL 或事件驱动失效；支付前以服务端校验为准。
Agent Card	可缓存数分钟；发布新版本后主动刷新。
搜索结果	注意 demo-search 限流；避免高频相同查询。

SSE 与流式接口

• 对 ai-create 等 SSE 端点，按 事件类型 解析，设置合理读超时与断线重连；重连策略同样建议指数退避。
• 流结束后务必以非流式接口或列表接口核对最终资源 ID 与状态。

安全

• API Key 仅存放在服务端或安全密钥管理；勿写入前端 bundle 或公共仓库。
• X-Platform-User-Id 表示 Key 当前代理的用户，需在集成侧做好租户隔离与审计。