云端 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.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>"
  }
}

错误响应内容

属性 值类型 描述

code

整数

错误代码。我们建议您围绕错误代码(而不是子代码或 HTTP 响应状态代码)来构建应用的错误处理逻辑。

details

字符串

有关错误及其最可能原因的描述。可能还包含有关如何处理错误的信息,例如哪个参数无效或可接受哪些值。

error_subcode

整数

已停用。不会在 v16.0 及更高版本的响应中返回。


图谱 API 子代码。不是所有响应都会包含子代码,因此我们建议您改为围绕 codedetails 属性来构建错误处理逻辑。

fbtrace_id

字符串

可在联系站内支持时使用的追踪编号。此编号可帮助我们调试错误。

message

字符串

错误代码及其名称的组合。示例:(#130429) Rate limit hit

messaging_product

字符串

消息产品。对于云端 API 响应,此值始终是字符串 whatsapp

type

字符串

错误类型。

响应示例

{
  "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 状态代码

0

身份验证异常

我们无法验证应用用户。

通常,这表示包含的访问口令已过期、失效,或应用用户为防止所有应用访问其数据而更改了设置。我们建议您获取新的访问口令

401

未授权

3

API 方法

功能或权限问题。

使用访问口令调试器来确认您的应用已获得端点所需权限。请参阅疑难解答

500

内部服务器错误

10

权限遭拒

未获得权限或权限已被移除。

使用访问口令调试工具来确认您的应用是否已获得端点所需的权限。请参阅疑难解答

请确保已将用于设置企业公钥的电话号码列入白名单。

403

禁止访问

190

访问口令已过期

您的访问口令已过期。

获取新的访问口令

401

未授权

200-299

API 权限

未获得权限或权限已被移除。

使用访问口令调试工具来确认您的应用是否已获得端点所需的权限。请参阅疑难解答

403

禁止访问

节流错误

代码 描述 合理解决方案 HTTP 状态代码

4

API 调用过多

此应用已达到 API 调用流量限制。

应用面板中加载此应用,然后查看应用流量限制部分,确认此应用是否已达到其流量限制。如果已达到,请稍后再试,或减少此应用进行 API 查询的频次或数量。

400

错误请求

80007

流量限制问题

WhatsApp Business 帐号已达到其流量限制。

参阅 WhatsApp Business 帐号的流量限制。稍后重试;或减少此应用进行 API 查询的频次或数量。

400

错误请求

130429

达到流量限制

已达到云端 API 消息吞吐量。

此应用已达到 API 吞吐量限制。请参阅吞吐量。稍后重试;或减少此应用发送消息的频次。

400

错误请求

131048

达到垃圾信息流量限制

此电话号码被限制了可发送的消息数量,因此消息发送失败。这可能是因为之前有太多消息被封锁,或被标记为垃圾信息。

在 WhatsApp 管理工具中检查您的质量状态,然后查看基于质量的流量限制文档,以了解详情。

400

错误请求

131056

达到(商业帐号、消费者帐号)配对流量限制

短时间内从发信人手机号发送到同一收信人手机号的消息过多。

如需发送消息到同一电话号码,等待并重试操作。您仍可发送消息到其他电话号码,而无需等待

400

错误请求

133016

超出账户注册注销数量限制

由于短时间内尝试次数太多,未能成功注册或注销此手机号

此商家手机号因达到注册/注销的尝试次数上限而遭到封锁。号码解除封锁后,请再试一次。请查看注册文档的“限制”部分。

400

错误请求

诚信错误

代码 描述 合理解决方案 HTTP 状态代码

368

因违反政策被暂时禁用

由于违反平台政策,与该应用绑定的 WhatsApp Business 帐号已被限制或停用。

参阅政策执行文档,了解政策违规内容及其解决方案。

403

禁止访问

130497

商业帐号被限制向此国家/地区的用户发送消息。

此 WhatsApp Business 帐号被限制向某些国家/地区的用户发送消息。

请参阅 WhatsApp Business 消息政策,详细了解在您的业务类别中允许接收 WhatsApp Business 帐号所发消息的国家/地区。

403

禁止访问

131031

帐号已锁定

由于违反平台政策,与此应用绑定的 WhatsApp Business 帐号已被限制或停用,或者我们无法根据 WhatsApp Business 帐号上的数据集来验证请求中包含的数据(例如,请求中包含的两步 PIN 码不正确)。

参阅政策执行文档,了解政策违规内容及其解决方案。


您还可以使用运行状况 API,此 API 可以提供有关帐号锁定原因的更多见解。

403

禁止访问

其他错误

代码 描述 合理解决方案 HTTP 状态代码

1

未知 API

请求无效或可能出现服务器错误。

访问 WhatsApp Business 开放平台状态页面,查看 API 状态信息。如果服务器没有中断,则参阅端点参考文档,并确认您的请求格式是否正确且满足所有端点要求。

400

错误请求

2

API 服务

因停机或过载而出现临时问题。

访问 WhatsApp Business 开放平台状态页面,查看 API 状态信息,然后重试。

503

服务不可使用

33

参数值无效

商家手机号已被删除。

确认公司电话号码是否正确。

400

错误请求

100

无效参数

请求中包含一个或多个不受支持或拼写错误的参数。

参阅此端点的参考文档,确定哪些参数受支持以及如何拼写。

在设置企业公钥时,请确保使用 PEM 格式的有效 2048 位 RSA 公钥

请确保您注册的手机号编号与之前存储的手机号编号相符。

确保您的参数具有相关类型的任何长度限制。

400

错误请求

130472

用户编号涉及试验

作为试验的一部分,消息未送出。

请参阅营销消息试验

400

错误请求

131000

出错了

出现未知错误,因此消息发送失败。

设置企业公钥时,这通常是因为系统计算签名或调用 GraphQL 端点失败,或者 GraphQL 端点返回错误。

再试一次。如果错误持续存在,则开立站内支持工单。

500

内部服务器错误

131005

访问遭拒

未获得权限或权限已被移除。

使用访问口令调试工具来确认您的应用是否已获得端点所需的权限。请参阅疑难解答

403

禁止访问

131008

必要参数缺失

请求中缺少一个必要参数。

参阅此端点的参考文档,确定哪些是必要参数。

400

错误请求

131009

参数值无效

一个或多个参数值无效。

参阅此端点的参考文档,确定每个参数的哪些值受支持;参阅电话号码,了解如何在 WhatsApp Business 商业帐号中添加电话号码。

400

错误请求

131016

服务不可使用

服务暂时不可使用。

访问 WhatsApp Business 开放平台状态页面,查看 API 状态信息,然后重试。

500

内部服务器错误

131021

收信人不能是发信人

发信人和收信人的电话号码相同。

将消息发送到与发信人不同的电话号码。

400

错误请求

131026

消息无法送达

无法送达消息。原因可包括:

  • 收信人手机号不是 WhatsApp 手机号。
  • 向国家/地区呼叫代码为 +91(印度)的 WhatsApp 用户发送身份验证模板。但目前,无法向印度境内的 WhatsApp 用户发送身份验证模板。
  • 收信人尚未接受我们的新服务条款和隐私政策。
  • 收信人使用了 WhatsApp 的旧版本;必须使用以下 WhatsApp 版本或更高版本:
    • Android:2.21.15.15
    • SMBA:2.21.15.15
    • iOS:2.21.170.4
    • SMBI:2.21.170.4
    • KaiOS:2.2130.10
    • 网页版:2.2132.6

使用非 WhatsApp 联系方式,请 WhatsApp 用户执行以下操作:

  • 确认他们实际可以向您的 WhatsApp Business 手机号发送消息。
  • 确认他们已接受我们的最新服务条款(如果他们还未接受,在设置 > 帮助中,或在设置 > 应用程序信息中,系统会提示他们接受最新条款/政策)
  • 更新到最新版 WhatsApp 客户端。

400

错误请求

131042

商家支付资格问题

您的支付方式出错了。

参阅 WhatsApp Business 帐号的账单简介,确认您是否已正确设置账单。

常见问题:

  • WhatsApp Business 帐号未绑定业务账户
  • 额度超出上限
  • 未设置或启用信用额度(支付账户)
  • WhatsApp Business 商业帐号已被删除
  • WhatsApp Business 帐号暂时受限
  • 未设置时区
  • 未设置货币
  • 以代理身份发出的 MessagingFor 请求待处理或已驳回
  • 在无有效支付方式的情况下超出免费对话次数限制

400

错误请求

131045

证书不正确

由于手机号注册错误,消息发送失败。

注册电话号码,然后重试。

500

内部服务器错误

131047

再互动消息

距收信人上次回复发信人号码,时间已超过 24 小时。

改用消息模板向收信人发送商家发起的消息。

400

错误请求

131049

Meta 选择了不送达。

为保持健康的生态系统互动,这条消息未被送达。

如果您收到此错误代码,并怀疑是因受到限制而出现此代码,请勿立即重试。相反,您应该在重试时逐渐增加时间间隔,直到消息成功送达,因为该限制可能在不同的时间段内生效。

详情请访问每位用户的营销模板消息限制

400

错误请求

131051

消息类型不受支持

消息类型不受支持。

参阅消息,了解受支持的消息类型,然后使用受支持的消息类型重试。

400

错误请求

131052

媒体下载出错

无法下载用户发送的媒体。

我们无法下载此 WhatsApp 用户所发消息中包含的媒体。有关详情,参见收到此消息时触发的任何消息 Webhooks 中的 error.error_data.details 值。

使用非 WhatsApp 方式,请 WhatsApp 用户向您发送媒体文件。

400

错误请求

131053

媒体上传出错

无法上传消息中使用的媒体。

由于一个或多个原因(例如不支持的媒体类型),我们无法上传该媒体。

有关详情,参见此消息发送失败时触发的任何消息 Webhooks 中的 error.error_data.details 值。

建议您检查造成错误的任何媒体文件,并确认这些文件实际上属于支持的媒体类型。例如,在 UNIX 中,您可以通过命令行使用文件检查,来确定文件的 MIME 类型:

file -I rejected-file.mov

然后您可以确认其 MIME 类型是否受支持。参阅受支持的媒体类型

400

错误请求

131057

帐号处于维护模式

商业帐号目前处于维护模式

WhatsApp Business 帐号目前处于维护模式。其中一个原因可能是帐号正在进行吞吐量升级。

500

错误请求

132000

模板参数数量不一致

请求中包含的可变参数值数量与模板中定义的可变参数数量不一致。

参阅消息模板指南,确保请求中包含模板中定义的所有可变参数值。

400

错误请求

132001

模板不存在

该模板在特定语言中不存在,或尚未通过审核。

确保您的模板已通过审核,并且模板的名称和语言设置准确无误。请确保遵循消息模板指南

404

未找到

132005

模板填充文字过长

翻译文字过长。

查看 WhatsApp 管理工具,确认模板已翻译。请参阅质量评分与模板状态

400

错误请求

132007

违反模板格式字符政策

模板内容违反了 WhatsApp 政策。

参阅未通过审核的原因,确定违规的可能原因。

400

错误请求

132012

模板参数格式不一致

可变参数值格式不正确。

请求中包含的可变参数值未使用模板中指定的格式。参阅消息模板指南

400

错误请求

132015

模板已暂停

模板因低质量而暂停,因此您无法在模板消息中发送此模板。

编辑模板以提高其质量,在模板通过审核后重试。

400

错误请求

132016

模板已禁用

模板已多次因低质量而暂停,现已永久禁用。

使用不同内容新建模板。

400

错误请求

132068

流量被屏蔽

流量处于屏蔽状态。

纠正 Flow

400

错误请求

132069

流量被节流

流量处于节流状态,过去一小时内已发送了使用此流量的 10 条消息。

纠正流量

400

错误请求

133000

注销未完成

之前的注销尝试失败。

重新注销号码后再注册

500

内部服务器错误

133004

服务器暂时不可使用

服务器暂时不可使用。

访问 WhatsApp Business 开放平台状态页面,查看 API 状态信息,检查响应中的 details 值,然后重试。

503

服务不可使用

133005

两步验证 PIN 码不一致

两步验证 PIN 码不正确。

确认请求中包含的两步验证 PIN 码正确。


重置两步验证 PIN 码的做法:


  1. 禁用两步验证
  2. 手机号端点发送包含新 PIN 码的 POST 请求。

400

错误请求

133006

需要重新验证手机号

手机号需要重新验证,才能注册。

验证手机号后再注册。

400

错误请求

133008

两步验证 PIN 码输入错误次数过多

此手机号的两步验证 PIN 码输入错误次数过多。

details 响应值指定的时间后重试。

400

错误请求

133009

两步验证 PIN 码输入过于频繁

两步验证 PIN 码输入过于快速。

检查 details 响应值,然后重试。

400

错误请求

133010

手机号未注册

手机号未在 WhatsApp Business 开放平台上注册。

注册手机号,然后重试。

400

错误请求

133015

请等待几分钟,再尝试注册此手机号

您当前尝试注册的手机号近期被删除,但删除尚未完成。

请等待 5 分钟,再重新尝试发送请求。

400

错误请求

135000

一般用户错误

您的请求参数出现未知错误,因此消息发送失败。

参阅此端点的参考文档,确认您查询端点所使用的语法是否正确。如果您在响应中继续收到此错误代码,请联系客户支持

400

错误请求