• 覆盖 228 个目的地
  • 始终无需 KYC
  • 支持 Bitcoin、Monero、USDT 等 7 种币种

API 与集成

幂等密钥

幂等密钥是客户端随请求发送的自选标识符,使超时或错误后的重试返回原始结果,而不会重复发送消息。

网络总在最糟糕的时刻出故障:服务器已经执行了操作,而客户端还没收到结果。一个超时的请求可能已经发出了消息,也可能没有,客户端无从判断。没有幂等机制时,安全的做法是什么也不做;而诱人的做法,也就是重试,则有重复发送的风险。有了幂等密钥,客户端就可以放心重试:服务器识别出密钥,返回第一次尝试的结果,不会再发送任何新消息。

Idempotency-Key 标头是由支付 API 推广开来的惯例,此后被广泛采用。服务器会在有限的期限内保留密钥,而且许多服务器会拒绝带着不同有效载荷再次出现的同一密钥,因为这说明客户端有缺陷,而不是在重试。密钥应来自你自己的业务标识符,例如订单号加事件,或用户加尝试次数,这样来自不同进程或服务器的重试才能正确地落到同一个密钥上。密钥必须在第一次尝试之前创建,与任务一起保存,并在每次重试时原样重复使用。

示例

假设一家商店为订单 4821 发送发货通知,使用的密钥是 order-4821-shipped。第一次 POST 超时了。使用同一密钥的重试返回了原始消息 ID 和状态;客户只收到一条 SMS,账户也只为一条付费。如果重试使用了新密钥,客户就会收到两条。

常见错误

  • 每次重试都生成新的随机密钥,这完全违背了初衷。
  • 使用范围过宽的密钥(例如只用用户 ID),导致之后的不同消息被当作重放,永远不会发送。
  • 在重试循环内部创建密钥,而不是把它与任务一起持久保存。

在 SMSMeteor:任何 POST 请求都接受 Idempotency-Key,即由你自选、最长 128 个字符的字符串。24 小时内使用相同密钥和相同有效载荷:返回原始响应,并带有标头 Idempotent-Replayed: true。相同密钥、不同有效载荷:返回 409 idempotency_conflict。这一点很重要,因为消息一旦交给运营商就会计费,重复发送就意味着第二次扣费。收到 429 后,请等待 Retry-After 指定的时间,再用同一密钥重试。API 参考提供了详细信息,测试密钥则让你无需发送任何消息即可演练超时和重试。

深入了解

在实践中了解这个术语。一个电子邮箱地址即可开户,费率公开,支持加密货币付款,测试密钥免费。
开始发送