幂等、版本与错误处理
先辨别协议和执行状态,再决定是否重试。
网关写入约定
POST /v1/operations 要求 Idempotency-Key,8–100 字符;同一业务操作重试沿用原编号与正文。响应重放窗口为 24 小时、有大小上限;未知结果不能自动重新执行。revision 是配置并发控制,不能用幂等键代替。
常见 HTTP 状态
| 状态 | 处理 |
|---|---|
| 400 / 413 / 415 / 422 | 检查字段、正文大小、Content-Type 与接口专属校验;不要原样循环重试 |
| 401 / 403 | 检查密钥到期、撤销、操作权限、所属范围及企业 MFA 策略;不要换企业或绕过校验 |
| MFA_REQUIRED / STEP_UP_REQUIRED | 本人会话按同源 loginUrl 重新认证后手动确认;API Key 的 MFA_REQUIRED 是机器接入受限,登录或轮换均无效 |
| 402 | 检查接待余额 / 套餐准入;调用前失败不等于业务成功 |
| 409 | 检查 revision 或未知执行状态,先读回对账 |
| 429 | 按 Retry-After 等待,保留原幂等键 |
| 网络超时 / 5xx | 结果可能未知,记录请求 ID 和读取状态;勿生成新键盲重试 |
响应格式不可一概而论
网关保留底层响应类型;下载、流式 NDJSON 与普通 JSON 分开解析,NDJSON 不是 SSE。访客客户端使用 YunfuError.code / status / retryAfter 和 pending;历史使用 before / limit,不能套用通用 page / pageSize。
排查信息
记录 X-Request-Id、operationId、时间、环境、HTTP 状态和脱敏响应;在请求日志核对计费主体和操作结果。不记录 API Key、visitor Bearer、原始敏感正文。
官方原始接入文档
先按云蝠指南完成入口、智能体和服务配置,再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力,不代表云蝠已开放其中全部接口;腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。
- OpenAPI Initiative · OpenAPI Specification 3.1.0 ↗:理解本站 OpenAPI 文件的 schema、安全方案与导入格式;实际云蝠接口、字段和权限仍以本站接口参考为准。
实现依据 · 仓库内路径
app/v1/operations/developer-gateway.tslib/developer-docs/api-manual.tssdk/wechat-miniapp/index.d.ts
文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。