接入指南

请求入口

服务端 API 的入口为 https://{gateway_host}。请使用 HTTPS，并在服务端设置合理的连接、读取和整体超时。

统一响应

多数开放接口使用以下响应外壳：

{ "code": 200, "msg": "", "data": {} }

code=200 表示成功；code=500 表示业务失败。鉴权失败使用 HTTP 状态码，例如 401 INVALID_TOKEN 和 403 SCOPE_DENIED。OAuth 令牌和 UserInfo 接口使用 OAuth JSON 外壳，详见鉴权与签名。

通用请求规则

• 令牌按接口说明放在 Authorization: Bearer、Query 或表单中，同一请求只使用一种方式。
• Content-Type: application/json 的请求体必须是合法 JSON。
• 成员 ID、部门 ID、机器人 ID 按字符串传输。
• code 和 access_token 不写入日志、URL、埋点和错误上报。

错误与重试

类型	处理
400 参数错误	修正请求，不重试
401 令牌无效	重新获取令牌后重试一次
403 权限或 IP 不允许	检查权限配置，不重试
5xx 或网络超时	有限次数指数退避，并设置熔断
机器人业务失败	根据逐项错误和幂等键决定是否重试

查询接口天然幂等；机器人发送接口和事件回调必须由应用侧保证幂等。

错误码与限流

机器人接口同时存在 HTTP 层、请求级业务层和逐项投递层错误。

层级	典型错误	处理方式
HTTP	401 INVALID_TOKEN、403 SCOPE_DENIED、503	修复鉴权或有限退避
请求级	INVALID_REQUEST、PERMISSION_DENIED	修正请求，不重试无效参数
逐项结果	rejected、failed	按用户和错误码分类处理

重试规则

• 发送接口必须设置 Idempotency-Key，重试保持同一键和请求体。
• 网络超时和 5xx 可指数退避；4xx 参数、权限和可见范围错误不自动重试。
• 批量请求按业务大小分批，避免瞬时触达过多成员。
• 记录请求 ID、目标数量和结果汇总，不记录令牌、密钥和完整隐私内容。

平台限流策略可能调整。调用方应缓存 access_token、控制并发，并在收到限流或 503 时退避。