开发者指南
常见问题与排障
从具体症状出发，先确认环境与身份，再检查资源和投递状态。
登录后看不到资源
- 确认登录的是资源所属账号，且页面和 API 属于同一品牌环境。
- 机器人查看申请审核状态；客服确认域成员权限；应用确认拥有或被授权管理该资源。
- 产品入口本身缺失时，先确认当前环境是否启用了该能力。
401 / 403：鉴权或权限失败
- 检查 Authorization: Bearer 请求头、凭证类型、所属环境和是否已被轮换或吊销。
- 结合业务错误码检查审核、启用状态、资源归属、scope 和来源策略。
- Bot Token 可先调用 GET /bots/me 排除基础鉴权问题；不要重复重试错误凭证。
机器人收不到消息 / Webhook 失败
- 确认机器人已加入会话；群内普通消息可能受隐私模式过滤，先测试命令或提及。
- 检查 getWebhookInfo、投递日志和接收服务日志，确认 HTTPS 地址可达且 secret_token 已配置。
- 验签使用原始请求体，不要重新序列化 JSON；检查时间戳与服务器时钟。
- 如果使用 getUpdates，先关闭 Webhook；两种消费方式冲突时按 409 错误处理。
429 / 超时 / 重复事件
- 检查返回的限流信息与配额，降低并发，使用有上限的退避；不要立即无限重试。
- 超时后先核对业务结果；按各接口契约使用幂等键，Webhook 消费按 Update ID 去重。
发券或核销失败
- 检查应用和模板状态、Token 的操作权限、来源策略，以及是否满足请求加密要求。
- 按错误码确认库存或发放限制、接收者和券状态；已核销券不要重复履约。
- 平台核销成功但你的业务履约失败时，先核对本地记录，再按业务规则重试履约或申请冲正。
联系支持时提供什么？
- 品牌环境、出错时间和时区、接口路径与 HTTP 方法。
- HTTP 状态、业务错误码、请求 ID 或 Update ID，以及脱敏后的最小复现步骤。
- 预期结果、实际结果、是否每次发生，以及近期是否轮换凭证或变更来源配置。
请勿发送完整 Token、密码、Webhook secret 或用户隐私。凭证泄露后应立即轮换并更新服务端配置。