已经确认、还没修的行为差异。写在这里是为了让你现在就绕开，而不是踩到之后自己猜。

已知问题

这一页记的是我方已经确认为不合意、但还没改的行为。它们都不会报错 ——所以不写出来，你只会在生产上遇到，然后花时间怀疑自己。

每一条都给了「现在怎么写」。按那样写的代码，在我方修掉之后不需要改。

K-001 · 开卡申请的状态在两个端点上不一致

表现

POST /v1/cards/applications 下单时返回 status: "pending"；回查 GET /v1/cards/applications/{id} 时同一张单返回status: "pending_merchant_funds"。

下单那一侧是裁剪过的三档，回查那一侧是内部原文（20 档）。

为什么会咬到你

你按下单响应写的状态映射表里没有 pending_merchant_funds。一次「商户预付不足排队」在你的系统里会落进 default 分支 ——而多数人的 default 是「未知，当失败处理」。

现在怎么写

把 pending_merchant_funds 当 pending 处理，并对所有不认识的在途状态一律按「还在跑，继续轮询」处理，只把那 5 个终态硬编码。见状态机与取值。

我方会怎么修：收敛到裁剪那一侧（回查也只回三档 + 终态）。

K-002 · 介质由 form_factor 决定，product_id 说了不算

表现

POST /v1/cards/applications 的介质只看请求体的 form_factor：physical = 实体卡，其余一切取值（含大写 Physical、含缺省）都按虚拟卡处理。没有拼写校验，没有报错。

而 product_id 指向的产品行自己也有一个介质，我方在解析产品时读了它 —— 但没有用。于是：

为什么会咬到你

你以为下单的是实体卡，结果开出一张虚拟卡 —— 而且账也对得上（实体卡才收邮费，按虚拟卡走就不收，两边都自洽）。发现这件事通常是会员问「我的卡什么时候寄到」。

现在怎么写

product_id 与 form_factor 一起传，并且自己保证两者一致。 form_factor 用小写常量，别拼接、别透传用户输入。下单后回查详情核对返回的 form_factor 再告诉会员。

我方会怎么修：传了 product_id 时以产品行的介质为准；两者冲突、或 form_factor 认不出，一律 400。

K-003 · 不传 client_key 会随机生成一把

表现

POST /v1/cards/applications 的 client_key（业务层幂等键，落库、永久）不传时我方随机生成一把。

为什么会咬到你

请求头 x-idempotency-key 的窗口是 24 小时。超过 24 小时之后同一份 body 重发，两把键都不拦 —— 会真的开出第二张卡，并真的再扣一次开卡费。

现在怎么写

自己传 client_key，用你那边的业务主键。这是唯一一把永久的幂等键。

我方会怎么修：不打算改缺省行为（随机比固定安全），但会在下单响应里回显生效的 client_key，让你能核对。

K-004 · 部分端点的 failure_code 是空字符串而不是 null

表现

拿不到具体失败原因时，failure_code 是 ""。

现在怎么写

判空用 falsy 判断（if (!failure_code)），别用 === null。出参里的所有可选字符串字段都按这条处理。

已修（留档，方便你确认自己绕开的写法可以撤了）

怎么报一条新的

带上响应里的 request_id 找我方 —— 那个 ID 能定位到具体一次调用。确认之后会加到这一页，并给出「现在怎么写」。