错误响应

所有 InnoPaaS API 都返回相同的 JSON 错误响应结构。请使用六位 code 判断发生了什么，以及下一步应该怎么处理。

HTTP 状态码只表示粗粒度结果。2xx 响应仍可能包含非成功的业务 code，因此必须检查响应体。

响应结构

{
  "code": "010003",
  "message": "The value of 'to' is invalid. Use an E.164 number such as +6581234567.",
  "data": null,
  "traceId": "d87a93e50af0437ebcc0c80774126842",
  "timestamp": "2026-10-21T03:00:01.000Z"
}

字段	类型	说明
`code`	string	必填。六位数字字符串；`000000` 表示成功。
`message`	string	必填。供人阅读的说明，不得作为程序判断依据。
`data`	object, array, or null	必填。业务结果；请求整体失败时为 `null`。
`traceId`	string	必填。排查凭证，用于关联支持请求与内部日志。
`timestamp`	string	必填。响应生成时间，UTC ISO 8601，毫秒精度，以 `Z` 结尾。

如何处理错误

情况	建议动作
请求、凭证、权限、余额或配置有误	修复原因后重新提交。
限流或临时故障有可靠恢复时间	有 `Retry-After` 时至少等待该时长；否则使用有上限的指数退避。
原请求可能已受理	先查询原请求，再决定是否重发；支持幂等键时复用原幂等键和原内容。
消息被拒或投递失败	不自动重发。再次发送属于新的业务操作，可能产生费用。
遇到未文档化的错误码	记录 `code`、`message` 和 `traceId`，停止自动重试并联系支持。

发送请求成功仅表示已受理，不代表消息已经送达。

错误码目录

码段	归属	范围
`000000`	成功	本次接口操作成功
`01xxxx`	请求与资源	参数、格式、资源、状态与幂等冲突
`02xxxx`	身份与访问	API Key、权限、IP、账户、开通与鉴权
`03xxxx`	计费与额度	余额、授信、周期额度和计费配置
`04xxxx`	频率与并发	请求速率、发送速率、并发
`05xxxx`	平台服务	内部异常、不可用、结果待确认
`06xxxx`—`09xxxx`	通用预留	统一申请后分配
`202xxx`	SMS	短信提交规则与投递结果
`11xxxx`	WhatsApp	产品专属错误，具体编码另行制定
`12xxxx`	Voice	产品专属错误，具体编码另行制定
`13xxxx`	万数	产品专属错误，具体编码另行制定
`14xxxx`	Email
`15xxxx`	rcs/mms
`16xxxx`
`14xxxx`—`89xxxx`	后续产品预留	按产品线分配
`90xxxx`—`99xxxx`	暂不分配	保留扩展

目标 HTTP 状态码映射

下表为目标映射。当前短信发送接口仍以 HTTP 200 返回业务错误，请以响应体 code 判断；迁移完成前，具体接口的实际行为以其 API 文档为准。

错误码范围	HTTP 状态码
`010001`–`010003`, `010011`–`010013`	`400`
`010004`	`413`
`010005`	`404`
`010006`–`010008`	`409`
`010009`	`405`
`010010`	`415`
`020001`, `020002`, `020008`, `020009`	`401`
`020003`–`020007`	`403`
`030001`, `030002`	`402`
`030003`, `030004`	`403`
`030005`	`503`
`040001`–`040003`	`429`，并提供 `Retry-After`
`050001`	`500`
`050002`	`503`
`050003`	`504`
`100001`–`100010`	`422`
`100011`	`503`
`101xxx`	不作为发送请求的 HTTP 错误；见查询结果或事件数据

相关文档

响应结构

{
  "code": "010003",
  "message": "The value of 'to' is invalid. Use an E.164 number such as +6581234567.",
  "data": null,
  "traceId": "d87a93e50af0437ebcc0c80774126842",
  "timestamp": "2026-10-21T03:00:01.000Z"
}

字段	类型	说明
`code`	string	必填。六位数字字符串；`000000` 表示成功。
`message`	string	必填。供人阅读的说明，不得作为程序判断依据。
`data`	object, array, or null	必填。业务结果；请求整体失败时为 `null`。
`traceId`	string	必填。排查凭证，用于关联支持请求与内部日志。
`timestamp`	string	必填。响应生成时间，UTC ISO 8601，毫秒精度，以 `Z` 结尾。

如何处理错误

情况	建议动作
请求、凭证、权限、余额或配置有误	修复原因后重新提交。
限流或临时故障有可靠恢复时间	有 `Retry-After` 时至少等待该时长；否则使用有上限的指数退避。
原请求可能已受理	先查询原请求，再决定是否重发；支持幂等键时复用原幂等键和原内容。
消息被拒或投递失败	不自动重发。再次发送属于新的业务操作，可能产生费用。
遇到未文档化的错误码	记录 `code`、`message` 和 `traceId`，停止自动重试并联系支持。

发送请求成功仅表示已受理，不代表消息已经送达。

错误码目录

码段	归属	范围
`000000`	成功	本次接口操作成功
`01xxxx`	请求与资源	参数、格式、资源、状态与幂等冲突
`02xxxx`	身份与访问	API Key、权限、IP、账户、开通与鉴权
`03xxxx`	计费与额度	余额、授信、周期额度和计费配置
`04xxxx`	频率与并发	请求速率、发送速率、并发
`05xxxx`	平台服务	内部异常、不可用、结果待确认
`06xxxx`—`09xxxx`	通用预留	统一申请后分配
`202xxx`	SMS	短信提交规则与投递结果
`11xxxx`	WhatsApp	产品专属错误，具体编码另行制定
`12xxxx`	Voice	产品专属错误，具体编码另行制定
`13xxxx`	万数	产品专属错误，具体编码另行制定
`14xxxx`	Email
`15xxxx`	rcs/mms
`16xxxx`
`14xxxx`—`89xxxx`	后续产品预留	按产品线分配
`90xxxx`—`99xxxx`	暂不分配	保留扩展

目标 HTTP 状态码映射

下表为目标映射。当前短信发送接口仍以 HTTP 200 返回业务错误，请以响应体 code 判断；迁移完成前，具体接口的实际行为以其 API 文档为准。

错误码范围	HTTP 状态码
`010001`–`010003`, `010011`–`010013`	`400`
`010004`	`413`
`010005`	`404`
`010006`–`010008`	`409`
`010009`	`405`
`010010`	`415`
`020001`, `020002`, `020008`, `020009`	`401`
`020003`–`020007`	`403`
`030001`, `030002`	`402`
`030003`, `030004`	`403`
`030005`	`503`
`040001`–`040003`	`429`，并提供 `Retry-After`
`050001`	`500`
`050002`	`503`
`050003`	`504`
`100001`–`100010`	`422`
`100011`	`503`
`101xxx`	不作为发送请求的 HTTP 错误；见查询结果或事件数据

响应结构

如何处理错误

错误码目录

目标 HTTP 状态码映射

相关文档

相关主题

错误响应

响应结构

如何处理错误

错误码目录

目标 HTTP 状态码映射

相关文档

相关主题