错误与 HTTP 状态码

错误封装格式

{
  "error": {
    "code": "validation",
    "message": "Missing required field: phone"
  }
}

HTTP 状态码

状态码	含义
200	成功
201	已创建
202	已接受（排队 / 异步处理）
400	验证错误 / 请求无效
401	API 密钥缺失或无效
403	权限范围、IP 或合作伙伴不被允许
404	未找到资源
422	语义验证错误（例如表单字段）
429	超出速率限制
500	服务器错误

常见 error.code 值

代码	说明
unauthorized	API 密钥或令牌无效
forbidden	缺少权限范围、IP 被拒绝或合作伙伴不匹配
validation	请求正文无效
not_found	ID、手机号码或模板不存在
blocked	账户已选择退出
bot_error	流程或机器人引擎错误

投递状态（消息）

状态	含义
queued	已接受，但尚未完成投递
sending	正在发送
delivered	已投递到渠道 / 应用内
read	用户已读（如启用跟踪）
failed	所有渠道均失败
expired	已过期

幂等性冲突

重复使用同一个 idempotency_key 时，会返回原始消息和 200，而不会创建重复消息。