此云端 API 基于图谱 API 而构建,如果您对处理图谱 API 错误响应不熟悉,请参阅图谱 API 错误处理文档。
一般来说,我们建议您围绕 code
值和 details
负载属性构建应用的错误处理逻辑。这些属性及其值更能反映出基本错误。
作为 message
值的一部分,代码名称在 API 错误响应负载中没有专用属性。但是,我们建议您不要采用代码名称来构建错误处理逻辑,因为代码名称最终会停用。
云端 API 错误要么作为图谱 API 的响应同步返回,要么通过 Webhooks 异步返回,要么有时通过这两种方法返回。
使用云端 API 时,建议同时监控图谱 API 响应和 messages
Webhooks,以进行错误处理。如果订阅了 messages
Webhooks 字段,在发生受支持异步错误类型的错误时,您就会收到通知。
云端 API 错误可显示在以下 Webhooks 对象中:
云端 API
entry.changes.value.errors
entry.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 消息政策,详细了解在您的业务类别中允许接收 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 小时。 | 改用消息模板向收信人发送商家发起的消息。 |
错误请求 |
Meta 选择了不送达。 | 为保持健康的生态系统互动,这条消息未被送达。 | 如果您收到此错误代码,并怀疑是因受到限制而出现此代码,请勿立即重试。相反,您应该在重试时逐渐增加时间间隔,直到消息成功送达,因为该限制可能在不同的时间段内生效。 详情请访问每位用户的营销模板消息限制。 |
错误请求 |
消息类型不受支持 | 消息类型不受支持。 | 参阅消息,了解受支持的消息类型,然后使用受支持的消息类型重试。 |
错误请求 |
媒体下载出错 | 无法下载用户发送的媒体。 | 我们无法下载此 WhatsApp 用户所发消息中包含的媒体。有关详情,参见收到此消息时触发的任何消息 Webhooks 中的 使用非 WhatsApp 方式,请 WhatsApp 用户向您发送媒体文件。 |
错误请求 |
媒体上传出错 | 无法上传消息中使用的媒体。 | 由于一个或多个原因(例如不支持的媒体类型),我们无法上传该媒体。 有关详情,参见此消息发送失败时触发的任何消息 Webhooks 中的 建议您检查造成错误的任何媒体文件,并确认这些文件实际上属于支持的媒体类型。例如,在 UNIX 中,您可以通过命令行使用文件检查,来确定文件的 MIME 类型:
然后您可以确认其 MIME 类型是否受支持。参阅受支持的媒体类型。 |
错误请求 |
帐号处于维护模式 | 商业帐号目前处于维护模式 | WhatsApp Business 帐号目前处于维护模式。其中一个原因可能是帐号正在进行吞吐量升级。 |
错误请求 |
模板参数数量不一致 | 请求中包含的可变参数值数量与模板中定义的可变参数数量不一致。 | 参阅消息模板指南,确保请求中包含模板中定义的所有可变参数值。 |
错误请求 |
模板不存在 | 该模板在特定语言中不存在,或尚未通过审核。 | 确保您的模板已通过审核,并且模板的名称和语言设置准确无误。请确保遵循消息模板指南。 |
未找到 |
模板填充文字过长 | 翻译文字过长。 | 查看 WhatsApp 管理工具,确认模板已翻译。请参阅质量评分与模板状态。 |
错误请求 |
违反模板格式字符政策 | 模板内容违反了 WhatsApp 政策。 | 参阅未通过审核的原因,确定违规的可能原因。 |
错误请求 |
模板参数格式不一致 | 可变参数值格式不正确。 | 请求中包含的可变参数值未使用模板中指定的格式。参阅消息模板指南。 |
错误请求 |
模板已暂停 | 模板因低质量而暂停,因此您无法在模板消息中发送此模板。 | 编辑模板以提高其质量,在模板通过审核后重试。 |
错误请求 |
模板已禁用 | 模板已多次因低质量而暂停,现已永久禁用。 | 使用不同内容新建模板。 |
错误请求 |
流量被屏蔽 | 流量处于屏蔽状态。 | 纠正 Flow |
错误请求 |
流量被节流 | 流量处于节流状态,过去一小时内已发送了使用此流量的 10 条消息。 | 纠正流量 |
错误请求 |
注销未完成 | 之前的注销尝试失败。 |
内部服务器错误 | |
服务器暂时不可使用 | 服务器暂时不可使用。 | 访问 WhatsApp Business 开放平台状态页面,查看 API 状态信息,检查响应中的 |
服务不可使用 |
两步验证 PIN 码不一致 | 两步验证 PIN 码不正确。 | 确认请求中包含的两步验证 PIN 码正确。 重置两步验证 PIN 码的做法: |
错误请求 |
需要重新验证手机号 | 手机号需要重新验证,才能注册。 | 验证手机号后再注册。 |
错误请求 |
两步验证 PIN 码输入错误次数过多 | 此手机号的两步验证 PIN 码输入错误次数过多。 | 在 |
错误请求 |
两步验证 PIN 码输入过于频繁 | 两步验证 PIN 码输入过于快速。 | 检查 |
错误请求 |
手机号未注册 | 手机号未在 WhatsApp Business 开放平台上注册。 | 注册手机号,然后重试。 |
错误请求 |
请等待几分钟,再尝试注册此手机号 | 您当前尝试注册的手机号近期被删除,但删除尚未完成。 | 请等待 5 分钟,再重新尝试发送请求。 |
错误请求 |
一般用户错误 | 您的请求参数出现未知错误,因此消息发送失败。 |
错误请求 |