md2wechat API 常见错误排查：401、400、主题无效、试用 key 过期怎么处理

调接口最浪费时间的地方，是不知道先查什么。

所以这篇文章按最短排查顺序来。

你可以先记这一条：

先查 key，再查请求头，再查参数，再查主题，最后查请求体。

第一类：401

这类问题先别怀疑服务，先看认证。

场景 1：没传 API Key

最直接的情况。

先查：

• 有没有传 X-API-Key
• 有没有传 Md2wechat-API-Key
• 有没有传 Authorization: Bearer ...

只要一个都没传，接口就会直接拒绝。

场景 2：key 格式不对

当前只支持这 3 类前缀：

• wme_
• wme2_
• wmt_

如果你改了前缀、长度不对，或者自己拼了一个看起来像 key 的字符串，接口会直接拒绝。

场景 3：试用 key 已过期

如果你用的是 wmt_，还要多看一步：

• 这把 key 是不是已经过了统一失效时间

试用 key 过期后，接口会明确提示已经失效。

场景 4：key 被禁用

如果某把 key 已经被拉进禁用名单，就算它原来是有效的，也会直接失效。

这个场景最容易误判成“接口突然坏了”，其实不是，是 key 已经被回收。

第二类：400

这类大多属于请求内容本身的问题。

场景 1：markdown 为空

最常见。

先查：

• 是不是传了空字符串
• 字段名是不是写错了
• 你是不是只传了别的参数，没传正文

场景 2：请求体不是合法 JSON

比如：

• 少了引号
• 少了逗号
• 直接把多行内容原样塞进去，没有转义

这类错误经常出现在手写 curl 的时候。

场景 3：主题名无效

如果你传了一个系统不存在的主题名，接口会直接拒绝。

不要靠猜。

最稳的做法是：

• 去主题画廊确认
• 直接复制已经存在的主题名

场景 4：字号值不对

如果 fontSize 传了系统不认识的值，也会失败。

最稳只用：

• small
• medium
• large

第三类：看起来成功了，但结果不是你想要的

这类问题更常见。

场景 1：主题没生效

优先查：

• 主题名是不是写错了
• 你是不是根本没传 theme
• 你是不是在本地以为选了一个主题，但 API 实际没收到

场景 2：字号看起来不明显

这通常是预期太大。

fontSize 只是字号层面的调整，不是整套版面风格切换。

场景 3：拿到 HTML 了，但没法直接用

先确认你取的是不是：

• data.html

不要把整个响应对象当作 HTML；转换结果位于 data.html。

最短排查顺序

如果你希望最快定位，按这个顺序来：

1. 看状态码是 401 还是 400
2. 401 先查 key 和请求头
3. 400 先查 markdown 和 JSON
4. 再查主题名
5. 最后查字号和背景

这个顺序比“从头到尾重读文档”有效得多。

一条最稳的排查请求

当你不知道哪里出了问题时，先退回到这条最小请求：

curl -X POST "https://www.md2wechat.cn/api/convert" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wme2_your_api_key_here" \
  -d '{
    "markdown": "# 标题\n\n这是一段正文。"
  }'

如果这条都不通，先不要继续加别的参数。
先把最小请求调通，再往上叠。

什么时候应该怀疑是 key 问题？

下面这几种情况，优先怀疑 key：

• 你最近刚换过 key
• 你拿的是试用 key
• 同一份请求昨天能用，今天突然不行
• 别的参数都没动，只是认证突然失败

什么时候应该怀疑是参数问题？

下面这几种，优先查参数：

• 你最近刚改过主题名
• 你刚开始手写 JSON
• 你一口气加了很多参数
• 你把 Markdown 内容直接拼进命令里，没有处理换行

推荐排查顺序

不要每次都从完整请求开始排。

更高效的做法是：

1. 先调最小请求
2. 再加主题
3. 再加字号
4. 再加背景

这样你永远知道是哪一步出了问题。

如果你还没拿到 key

那就不要卡在排错上了，先去申请：

• 如何获取 md2wechat API Key

如果你还没跑通过第一条请求，先看：

• md2wechat API 快速开始