常见问题
选型：SDK 还是平台
Q：我直接用 Quick SMS SDK 就行了，为什么还要用平台？
只调一家厂商、团队能自己维护密钥和回调，SDK 完全够用，少一层依赖。
平台的适用场景是**「不止一家」之后出现的那层麻烦**：多渠道分发与容灾、多业务线共用、排障要在多个后台之间切、密钥轮换要改多个服务。这些问题的解法在平台上是控制台操作，在自建里是新的代码。判断标准见 章节首页的选型表。
Q：两个一起用会不会冲突？
不冲突，而且是推荐组合。SDK 直连你自己的 CPaaS 账号，平台也用你自己的同一批账号 —— 两边共享账号，但走各自的调用路径。典型分工：
- 验证码等对延迟敏感的主链路 → SDK 直连，路径最短
- 通知 / 营销 / 多业务线 → 平台，统一管理、统一观测
Q：平台用的是 Quick SMS 的那套适配器吗？
是。平台内部的多厂商发信由 Quick SMS 提供，你已支持的供应商在平台上同样可用。
接入
Q：接口一直返回 HTML，不是 JSON？
域名用错了。接口只在 smsapi.whaleal.com；sms.whaleal.com 是前端站点，任意路径都会回落到首页 HTML。见 基址说明。
Q：密钥正确但发信被拒，返回 40000？
最常见的原因是密钥没有绑定任何渠道。签发密钥分两步，只做完第一步（填名称）是发不了信的 —— 到密钥详情页的「渠道与路由」把渠道勾上。其它可能：没有 ACTIVE 渠道、参数缺失、号码不是 E.164 格式。
Q：submitted 之后要等多久才有终态？
取决于底层供应商的回执速度，通常是秒级到分钟级。不接状态回调的话就只能轮询状态接口。
Q：to 必须写 E.164 格式吗？
是，形如 +14155550123（国家码开头，加号，不带空格和短横线）。国内号码也要带 +86。
Q：发送超时了，我重试了一次，结果客户收到两条。
这是重发红线。平台没有幂等键，超时不代表没发。请改掉"超时即重试"的通用重试逻辑，对发送接口单独处理：超时后去控制台消息日志用「时间窗 + 接收号码」自查。
Q：可以在前端（浏览器 / 小程序）直接调吗？
不可以。 sk_ 密钥是服务端凭据，前端持有等于公开。正确做法是前端调你自己的后端，由后端持有密钥。
错误码排错
| 业务码 | HTTP | 常见原因 | 处理 |
|---|---|---|---|
| — | 200 但不是 JSON | 域名用了 sms.whaleal.com | 换成 smsapi.whaleal.com |
40100 | 401 | 没带密钥 / 密钥被禁用 / 抄漏了字符 | 检查 Authorization 头；必要时重新签发 |
40000 | 400 | 密钥未绑定渠道、无 ACTIVE 渠道、参数缺失、号码格式不对 | 按"接入"一节逐项排查 |
40300 | 403 | 租户被限制 | 联系支持 |
40400 | 404 | messageId 不存在，或不属于本租户 | 确认用的是本次发送返回的 ID |
42900 | 429 | 超套餐 QPS；若 msg 以 edge rate limit exceeded 开头则是边缘层 | 指数退避重试；持续出现说明该升档或该收敛客户端速率 |
50000 | 500 | 平台内部错误 | 退避重试；持续失败联系支持 |
数据与安全
Q：我的短信内容会被平台保存吗？
不会。 正文出于合规要求不落库。你需要自行留存业务侧发送记录。平台只保留支撑对账与排障的元数据（接收号码、状态、承运渠道、编码口径、计费条数、错误码）。
Q：我的供应商密钥存在哪里？
AES 加密存储，永不回显完整密钥（页面上只能看到前缀）。发送时按请求解密后传入发信引擎。
Q：供应商回执地址里的 token 是做什么的？
防伪造回执。同一个令牌也作为 X-Callback-Token 头推给你的系统，供你验证来源。重置令牌会让旧地址立即失效，需要回各供应商后台更新。
Q：能查别人的消息吗？
不能。状态查询强制校验租户归属，跨租户返回 40400。
对外口径（做宣传材料前请先读）
平台是 BYOL 多渠道短信中转平台。以下说法不能出现在官网、销售材料、客户邮件里：
| ❌ 不能说 | ✅ 应该说 |
|---|---|
| "省短信费" / "语音比价更低" | 短信资费由你自己的 CPaaS 账号决定，平台不加价；平台省的是多渠道的运维与开发成本 |
| "保证送达" | 平台负责提交与状态归一，投递结果由底层通道决定 |
| "替代 CPaaS" | 平台是叠加的管理层，你的 CPaaS 合同、号码、资费全部保留 |
| "合并账单 / 一条账单" | 短信费在供应商账单，平台订阅费在平台账单，两笔分开 |
官方自述口径（可直接引用）：
平台为 BYOL 多供应商统一管理平台：不售卖短信、不经手资费、不承诺送达、不改变底层链路。
需要报备的模板与签名，由客户在各 CPaaS 后台自行完成，平台内无审核流。
相关资源
| 资源 | 地址 |
|---|---|
| 控制台 | sms.whaleal.com |
| 线上 API 参考（可分享） | sms.whaleal.com/developers/api |
| 开发者页（多语言示例） | sms.whaleal.com/developers |
| 定价 | sms.whaleal.com/pricing |
| 帮助中心 | sms.whaleal.com/help |
| Quick SMS SDK 文档 | 本站 · GitHub |