一段过长描述为何导致 x402 收款失败

一个按次收费 $0.15 的接口，能正常返回 402，目录也能被检索到，却没有一笔付款成功。作者最后发现，触发故障的竟然是那段写给人看的服务介绍：509 个字符。

这篇记录值得看的地方，是它揭开了一种容易漏掉的跨系统故障：你生成的响应符合要求，不代表下游接受客户端据此组装的数据。对接支付、网关或第三方 API 时，单看接口健康和格式校验，可能会把技术故障误判成没人愿意买。

为什么服务介绍会挡住付款

作者运营的 minia2a 是一个 x402 按次付费市场，使用 Base 上的 USDC。按照原文说明，当前每个签名钱包有 5 次免费试用，无积分和充值通道，也不需要注册。这次故障记录的测量日期是 2026-10-31。

问题从 x402 的付款挑战开始。所谓挑战，就是服务端返回的一份文档，告诉客户端资源是什么、接受什么付款条件。服务介绍也在里面。

下面这段原始结构，展示了介绍文本为什么会进入支付链路：

{
  "resource": {
    "url": "https://minia2a.uk/x402/...",
    "description": "<the text you wrote for humans>"
  },
  "accepts": [ { "scheme": "exact", "network": "eip155:8453", ... } ]
}

要看的是 resource.description。这段是结构示意，包含省略号，不能直接当作完整 JSON 解析。

客户端读取挑战、决定付款后，会把这份文档复制进交给 facilitator 的支付载荷。facilitator 可以理解为负责校验和处理付款的中间服务。于是，原本用于目录展示的文案，也成了第三方要检查的数据。

服务端返回的挑战可以合规，下游付款仍然可能失败。作者收到的报错只有：

'paymentPayload' is invalid: must match one of [x402V2PaymentPayload, x402V1PaymentPayload]

这里要留意 paymentPayload：错误指向整个载荷及其 schema，没有告诉作者哪段文本过长，更没有提示去修改目录介绍。

「402 返回正确」和「这笔付款能通过」是两项不同的验收结果。

480 个字符是怎么来的，为什么不能直接照抄

作者固定其他字段，只改变介绍长度进行排查，测得边界落在 (450, 509]。他们没有继续确定精确阈值，也没有拿到公开的长度限制。

这里有两种可能：下游单独限制了介绍长度，或者限制的是整个载荷大小。如果是后者，accepts[] 里的 payTo 地址、network 字符串、asset 和扩展字段都会占空间。相同长度的介绍，换一套付款字段，结果也可能不同。

团队最终设置了 MAX_DESC_CHARS = 480，覆盖自己所有返回 402 的入口。它是运行时采用的经验上限，不是 x402 的协议常量。

原文还给了几组现场数据：

• 修复后的目录有 1,685 条自营记录，首次扫描发现 4 个超线服务，介绍分别长 699、515、493、485 个字符，均处于无法付款的状态；修改后缩短到 226–239 个字符。
• /x402/ai-audit 的线上 402 使用了 470 字符的介绍，PAYMENT-REQUIRED 响应头为 3,980 字节，其中 accepts 条目为 250 字节。
• 一次抽取 48 个 ID 的检查，漏掉了上述 4 条记录。

修复也不只是加一个长度判断。作者把它放进已有的 resource.description 检查中，先判断是否存在、是否属于占位内容，再判断长度。因此，一段 900 字符的占位文本，仍会优先被报告为占位问题。

他们还核对目录文案与实际 402 中的文本是否一致，其中最长的两条在两个入口上逐字节相同。转发的第三方条目则被排除，因为平台只是提供指向卖家的入口，无法决定对方返回什么挑战。

我的判断

作者最有说服力的判断，是要验证完整付款链路。

这类故障很容易藏在业务指标里：服务在线、目录可检索、挑战格式正常，客户也确实愿意付款，但交易被中间服务拒绝。由于没有交付记录，也不会形成退款案例。如果只看收入，团队可能把问题归因于需求不足。

不过，480 这个数必须打问号。它位于尚未确定的边界区间内，原文没有提供围绕这个值的完整通过、失败对照，更没有证明它适用于其他 facilitator 或其他载荷结构。作者也明确承认，真实限制可能是总载荷预算。

另外，字符数和字节数不能混用。原文用字符数设置护栏，又建议测量字节；对于中文介绍，这个区别尤其需要确认。原文没有交代字符的具体计数方式、编码及下游实际检查的对象，不能据此推出一个通用安全长度。

和单纯缩短文案相比，完整付款测试能直接回答交易是否成功；长度护栏则适合尽早拦住已知问题。两者各有用途。这份记录支持的是一次线上排障经验，没有足够的对照数据证明 480 是普遍可靠的方案。

能拿来做什么

• 如果你用 Node 接入 x402，在检查 402 结构之外，再安排实际付款验证，确认客户端提交的载荷能被目标 facilitator 接受。
• 如果目录和支付接口分别维护介绍文本，先核对实际输出是否一致，再做长度扫描，避免检查通过的是一份未进入付款流程的副本。
• 对自己维护的端点执行全量检查，并同时记录字符数、实际传输字节数和付款结果。采用 MAX_DESC_CHARS = 480 前，先验证自己的字段组合。
• 排查有访问却没有成交的服务时，把付款拒绝纳入检查范围，保留 facilitator 的具体错误，别只依赖收入与交付记录判断有没有需求。