错误码参考

所有 1Pass API 错误都以 JSON 格式返回：

{
    "error": "error_code",
    "message": "错误描述"
}

GET /start（登录发起）

错误码	HTTP	说明
not_found	404	路径不存在。请使用 /start，不要用其他路径
missing_site_id	400	缺少 site_id 参数
invalid_site_id	400	site_id 格式不合法
invalid_site	400	站点不存在或已禁用
login_provider_not_allowed	403	该站点未开通微信登录
rate_limited	429	请求过于频繁（30次/分钟/IP）
missing_env	500	服务端配置错误

POST /token（换取用户信息）

错误码	HTTP	说明
missing_auth_headers	400	缺少 X-1Pass-AK/Ts/Nonce/Sign 头
invalid_timestamp	400	时间戳格式不正确（必须是数字）
timestamp_out_of_range	401	时间戳与服务器时间相差超过 ±300 秒
invalid_ak	403	AK 不存在或已禁用
invalid_signature	403	签名验证失败（检查 SK 和签名算法）
nonce_reused	409	nonce 重复使用（5 分钟内不可重复）
invalid_json	400	请求体 JSON 格式错误
missing_ticket	400	缺少 ticket 字段
invalid_ticket_format	400	ticket 格式不合法
invalid_ticket	400	ticket 不存在、已使用或已过期（2 分钟有效期）
site_disabled	403	站点已被禁用
ticket_site_mismatch	403	ticket 不属于该 AK 对应的站点
insufficient_credits	403	积分不足，请在控制台充值
rate_limited	429	请求过于频繁（60次/分钟/AK）

支付接口错误

完整的支付错误码请参考 微信支付接入 — 支付错误码。

常见问题：通用

报错 {"error":"not_found"} 怎么办？

调用了不存在的接口路径。常见错误路径：

• ❌ /api/v1/wechat/authorize
• ❌ /oauth/authorize
• ❌ /api/wechat/login

1Pass 不是标准 OAuth2 接口，正确路径：

• ✅ 发起登录：GET /start?site_id=xxx
• ✅ 换取信息：POST /token
• ✅ 创建支付：POST /pay/wechat/native

redirect_uri 可以动态传吗？

不可以。出于安全考虑，回调地址只能在控制台配置。这确保了即使客户端被篡改，用户也不会被重定向到恶意网站。

可以直接从前端调用 /token 接口吗？

不可以。/token 接口需要 SK 签名，SK 绝不能暴露在前端代码中。必须由你的后端服务调用。

如何更新密钥？

在控制台的站点详情中点击「轮换密钥」，会生成新的 AK/SK。旧密钥立即失效，请及时更新你的后端配置。

有完整的接入示例吗？

可以参考 CodeBlog Demo，这是一个基于 Cloudflare Workers 的完整微信登录接入示例。

常见问题：登录

报错 invalid_signature 怎么排查？

1. 确认使用原始 SK — 使用 sk_... 原始字符串，不要对它做 SHA-256
2. 确认规范字符串格式 — 5 个部分之间是 \n（换行符），不是字面的 \\n
3. 确认路径 — 只用路径部分如 /token，不是完整 URL
4. 确认 body hash — 是请求体原文的 SHA-256，JSON 序列化后不能有多余空格
5. 确认 Base64Url 编码 — + → -，/ → _，去掉末尾 =
6. 确认时间戳是秒级 — 不是毫秒

报错 timestamp_out_of_range

服务器时间和客户端时间相差超过 5 分钟。请检查服务器时钟是否准确（建议使用 NTP 同步）。

报错 nonce_reused

同一个 nonce 在 5 分钟内被使用了两次。请确保每次请求生成新的 nonce（推荐使用 UUID）。

报错 invalid_ticket

ticket 已过期（2 分钟有效）或已被使用。ticket 是一次性的，只能换取一次。

报错 insufficient_credits

账户积分不足，请登录控制台充值。详见 积分系统。

unionid 为什么是 null？

unionid 需要微信开放平台应用绑定到同一个开放平台账号才会返回。如果你只需要唯一标识用户，使用 openid 即可。

nickname 和 headimgurl 为什么是 null？

受微信隐私政策影响，部分用户的昵称和头像可能无法获取。建议在你的应用中做好缺省值处理。

常见问题：支付

支付成功了但没收到回调通知怎么办？

1Pass 内置自动对账机制，每 5 分钟检查卡在"待支付"状态的订单，主动向微信查询实际状态。建议同时在前端轮询 status 接口作为备份。

金额单位是什么？

所有金额以分为单位。例如 ¥29.90 应传 2990。

同一个 out_trade_no 可以重复创建吗？

可以。如果订单号已存在，接口会返回已有订单信息（幂等设计），不会重复创建。

支持哪些登录和支付方式？

目前支持：

• 登录：微信扫码登录（PC 端）
• 支付：微信 Native 支付（PC 扫码付）

后续将支持支付宝等更多登录和支付方式。