云端 API 错误代码
此云端 API 基于图谱 API 而构建，如果您对处理图谱 API 错误响应不熟悉，请参阅图谱 API 错误处理文档。
一般来说，我们建议您围绕 code 值和 details 负载属性构建应用的错误处理逻辑。这些属性及其值更能反映出基本错误。
作为 message 值的一部分，代码名称在 API 错误响应负载中没有专用属性。但是，我们建议您不要采用代码名称来构建错误处理逻辑，因为代码名称最终会停用。
接收错误：同步和异步
云端 API 错误要么作为图谱 API 的响应同步返回，要么通过 Webhooks 异步返回，要么有时通过这两种方法返回。
使用云端 API 时，建议同时监控图谱 API 响应和 messages Webhooks，以进行错误处理。如果订阅了 messages Webhooks 字段，在发生受支持异步错误类型的错误时，您就会收到通知。
错误响应 Webhooks 和语法
云端 API 错误可显示在以下 Webhooks 对象中：
云端 API
entry.changes.value.errorsentry.changes.value.messages.errors
On-Premises API
errors
错误响应语法
{
"error": {
"message": "<MESSAGE>",
"type": "<TYPE>",
"code": <CODE>,
"error_data": {
"messaging_product": "whatsapp",
"details": "<DETAILS>"
},
"error_subcode": <ERROR_SUBCODE>
"fbtrace_id": "<FBTRACE_ID>"
}
}错误响应内容
| 属性 | 值类型 | 描述 |
|---|---|---|
| 整数 | 错误代码。我们建议您围绕错误代码（而不是子代码或 HTTP 响应状态代码）来构建应用的错误处理逻辑。 |
| 字符串 | 有关错误及其最可能原因的描述。可能还包含有关如何处理错误的信息，例如哪个参数无效或可接受哪些值。 |
| 整数 | 已停用。不会在 v16.0 及更高版本的响应中返回。 图谱 API 子代码。不是所有响应都会包含子代码，因此我们建议您改为围绕 |
| 字符串 | 可在联系站内支持时使用的追踪编号。此编号可帮助我们调试错误。 |
| 字符串 | 错误代码及其名称的组合。示例： |
| 字符串 | 消息产品。对于云端 API 响应，此值始终是字符串 |
| 字符串 | 错误类型。 |
响应示例
{
"error": {
"message": "(#130429) Rate limit hit",
"type": "OAuthException",
"code": 130429,
"error_data": {
"messaging_product": "whatsapp",
"details": "Message failed to send because there were too many messages sent from this phone number in a short period of time"
},
"error_subcode": 2494055,
"fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
}
}
错误代码
授权错误
| 代码 | 描述 | 合理解决方案 | HTTP 状态代码 |
|---|---|---|---|
身份验证异常 | 我们无法验证应用用户。 | 通常，这表示包含的访问口令已过期、失效，或应用用户为防止所有应用访问其数据而更改了设置。我们建议您获取新的访问口令。 |
未授权 |
API 方法 | 功能或权限问题。 |
内部服务器错误 | |
权限遭拒 | 未获得权限或权限已被移除。 | 使用访问口令调试工具来确认您的应用是否已获得端点所需的权限。请参阅疑难解答。 请确保已将用于设置企业公钥的电话号码列入白名单。 |
禁止访问 |
访问口令已过期 | 您的访问口令已过期。 |
未授权 | |
API 权限 | 未获得权限或权限已被移除。 |
禁止访问 |
节流错误
| 代码 | 描述 | 合理解决方案 | HTTP 状态代码 |
|---|---|---|---|
API 调用过多 | 此应用已达到 API 调用流量限制。 | 在应用面板中加载此应用，然后查看应用流量限制部分，确认此应用是否已达到其流量限制。如果已达到，请稍后再试，或减少此应用进行 API 查询的频次或数量。 |
错误请求 |
流量限制问题 | WhatsApp Business 帐号已达到其流量限制。 | 参阅 WhatsApp Business 帐号的流量限制。稍后重试；或减少此应用进行 API 查询的频次或数量。 |
错误请求 |
达到流量限制 | 已达到云端 API 消息吞吐量。 | 此应用已达到 API 吞吐量限制。请参阅吞吐量。稍后重试；或减少此应用发送消息的频次。 |
错误请求 |
达到垃圾信息流量限制 | 此电话号码被限制了可发送的消息数量，因此消息发送失败。这可能是因为之前有太多消息被封锁，或被标记为垃圾信息。 | 在 WhatsApp 管理工具中检查您的质量状态，然后查看基于质量的流量限制文档，以了解详情。 |
错误请求 |
达到（商业帐号、消费者帐号）配对流量限制 | 短时间内从发信人手机号发送到同一收信人手机号的消息过多。 | 如需发送消息到同一电话号码，等待并重试操作。您仍可发送消息到其他手机号，而无需等待 |
错误请求 |
超出帐户注册注销数量限制 | 由于短时间内尝试次数太多，未能成功注册或注销此手机号 | 此商家手机号因达到注册/注销的尝试次数上限而遭到封锁。号码解除封锁后，请再试一次。请查看注册文档的“限制”部分。 |
错误请求 |
诚信错误
| 代码 | 描述 | 合理解决方案 | HTTP 状态代码 |
|---|---|---|---|
因违反政策被暂时禁用 | 由于违反平台政策，与该应用绑定的 WhatsApp Business 帐号已被限制或停用。 | 参阅政策执行文档，了解政策违规内容及其解决方案。 |
禁止访问 |
帐号已锁定 | 由于违反平台政策，与此应用绑定的 WhatsApp Business 帐号已被限制或停用，或者我们无法根据 WhatsApp Business 帐号上的数据集来验证请求中包含的数据（例如，请求中包含的两步 PIN 码不正确）。 | 参阅政策执行文档，了解政策违规内容及其解决方案。 您还可以使用运行状况 API，此 API 可以提供有关帐号锁定原因的更多见解。 |
禁止访问 |
其他错误
| 代码 | 描述 | 合理解决方案 | HTTP 状态代码 |
|---|---|---|---|
未知 API | 请求无效或可能出现服务器错误。 | 访问 WhatsApp Business 开放平台状态页面，查看 API 状态信息。如果服务器没有中断，则参阅端点参考文档，并确认您的请求格式是否正确且满足所有端点要求。 |
错误请求 |
API 服务 | 因停机或过载而出现临时问题。 | 访问 WhatsApp Business 开放平台状态页面，查看 API 状态信息，然后重试。 |
服务不可用 |
参数值无效 | 商家手机号已被删除。 | 确认公司电话号码是否正确。 |
错误请求 |
无效参数 | 请求中包含一个或多个不受支持或拼写错误的参数。 | 参阅此端点的参考文档，确定哪些参数受支持以及如何拼写。 在设置企业公钥时，请确保使用 PEM 格式的有效 2048 位 RSA 公钥。 请确保您注册的手机号编号与之前存储的手机号编号相符。 确保您的参数具有相关类型的任何长度限制。 |
错误请求 |
用户编号涉及试验 | 作为试验的一部分，消息未送出。 | 请参阅营销消息试验。 |
错误请求 |
出错了 | 出现未知错误，因此消息发送失败。 在设置企业公钥时，这通常是因为系统计算签名或调用 GraphQL 端点失败，或者 GraphQL 端点返回错误。 | 请重试。如果错误持续存在，则开立站内支持工单。 |
内部服务器错误 |
访问遭拒 | 未获得权限或权限已被移除。 |
禁止访问 | |
必要参数缺失 | 请求中缺少一个必要参数。 | 参阅此端点的参考文档，确定哪些是必要参数。 |
错误请求 |
参数值无效 | 一个或多个参数值无效。 | 参阅此端点的参考文档，确定每个参数的哪些值受支持；参阅电话号码，了解如何在 WhatsApp Business 商业帐号中添加电话号码。 |
错误请求 |
服务不可使用 | 服务暂时不可使用。 | 访问 WhatsApp Business 开放平台状态页面，查看 API 状态信息，然后重试。 |
内部服务器错误 |
收信人不能是发信人 | 发信人和收信人的电话号码相同。 | 将消息发送到与发信人不同的电话号码。 |
错误请求 |
消息无法送达 | 无法送达消息。原因可包括：
| 使用非 WhatsApp 联系方式，请 WhatsApp 用户执行以下操作：
|
错误请求 |
商家支付资格问题 | 您的支付方式出错了。 | 参阅 WhatsApp Business 帐号的账单简介，确认您是否已正确设置账单。 常见问题：
|
错误请求 |
证书不正确 | 由于手机号注册错误，消息发送失败。 | 注册电话号码，然后重试。 |
内部服务器错误 |
再互动消息 | 距收信人上次回复发信人号码，时间已超过 24 小时。 | 改用消息模板向收信人发送商家发起的消息。 |
错误请求 |
消息类型不受支持 | 消息类型不受支持。 | 参阅消息，了解受支持的消息类型，然后使用受支持的消息类型重试。 |
错误请求 |
媒体下载出错 | 无法下载用户发送的媒体。 | 由于一个或多个原因，我们无法下载该媒体，例如不支持的媒体类型。如需详细了解我们无法下载该媒体的原因，请查看 使用非 WhatsApp 方式，请 WhatsApp 用户向您发送媒体文件。 |
错误请求 |
媒体上传出错 | 无法上传消息中使用的媒体。 | 由于一个或多个原因（例如不支持的媒体类型），我们无法上传该媒体。如需详细了解我们无法上传该媒体的原因，请查看 建议您检查造成错误的任何媒体文件，并确认这些文件实际上属于支持的媒体类型。 例如，在 UNIX 中，您可以通过命令行使用文件检查，来确定文件的 MIME 类型：
然后，您可以确认该文件的 MIME 类型是否在我们的支持的媒体类型清单中。 为了在发送媒体时获得更可靠的性能，请参阅媒体 HTTP 缓存和上传媒体。 |
错误请求 |
帐号处于维护模式 | 商业帐号目前处于维护模式 | WhatsApp Business 帐号目前处于维护模式。其中一个原因可能是帐号正在进行吞吐量升级。 |
错误请求 |
模板参数数量不一致 | 请求中包含的可变参数值数量与模板中定义的可变参数数量不一致。 | 参阅消息模板指南，确保请求中包含模板中定义的所有可变参数值。 |
错误请求 |
模板不存在 | 该模板在特定语言中不存在，或尚未通过审核。 | 确保您的模板已通过审核，并且模板的名称和语言设置准确无误。请确保遵循消息模板指南。 |
未找到 |
模板填充文字过长 | 翻译文字过长。 | 查看 WhatsApp 管理工具，确认模板已翻译。请参阅质量评分与模板状态。 |
错误请求 |
违反模板格式字符政策 | 模板内容违反了 WhatsApp 政策。 | 参阅未通过审核的原因，确定违规的可能原因。 |
错误请求 |
模板参数格式不一致 | 可变参数值格式不正确。 | 请求中包含的可变参数值未使用模板中指定的格式。参阅消息模板指南。 |
错误请求 |
模板已暂停 | 模板因低质量而暂停，因此您无法在模板消息中发送此模板。 | 编辑模板以提高其质量，在模板通过审核后重试。 |
错误请求 |
模板已禁用 | 模板已多次因低质量而暂停，现已永久禁用。 | 使用不同内容新建模板。 |
错误请求 |
流量被屏蔽 | 流量处于屏蔽状态。 | 纠正 Flow |
错误请求 |
流量被节流 | 流量处于节流状态，过去一小时内已发送了使用此流量的 10 条消息。 | 纠正流量 |
错误请求 |
注销未完成 | 之前的注销尝试失败。 |
内部服务器错误 | |
服务器暂时不可使用 | 服务器暂时不可使用。 | 访问 WhatsApp Business 开放平台状态页面，查看 API 状态信息，检查响应中的 |
服务不可使用 |
两步验证 PIN 码不一致 | 两步验证 PIN 码不正确。 | 确认请求中包含的两步验证 PIN 码正确。 重置两步验证 PIN 码的做法： |
错误请求 |
需要重新验证手机号 | 手机号需要重新验证，才能注册。 | 验证手机号后再注册。 |
错误请求 |
两步验证 PIN 码输入错误次数过多 | 此手机号的两步验证 PIN 码输入错误次数过多。 | 在 |
错误请求 |
两步验证 PIN 码输入过于频繁 | 两步验证 PIN 码输入过于快速。 | 检查 |
错误请求 |
手机号未注册 | 手机号未在 WhatsApp Business 开放平台上注册。 | 注册手机号，然后重试。 |
错误请求 |
请等待几分钟，再尝试注册此手机号 | 您当前尝试注册的手机号近期被删除，但删除尚未完成。 | 请等待 5 分钟，再重新尝试发送请求。 |
错误请求 |
一般用户错误 | 您的请求参数出现未知错误，因此消息发送失败。 |
错误请求 |