开发者文档中心

OpenAPI进入控制台

服务端 API 与回调 · 2026-10-31

幂等、版本与错误处理

先辨别协议和执行状态,再决定是否重试。

网关写入约定

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 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

实现依据 · 仓库内路径
  • app/v1/operations/developer-gateway.ts
  • lib/developer-docs/api-manual.ts
  • sdk/wechat-miniapp/index.d.ts

文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。