错误与排查
先定位失败发生在授权页面、令牌端点还是业务接口，再决定是否重新授权、修正配置或重试请求。
授权与令牌
| 错误或现象 | 常见检查点 | 处理方式 |
|---|---|---|
| 授权页无法继续 | 客户端状态、回调地址、Scope、PKCE 参数 | 核对已审核配置和本次请求 |
access_denied | 用户拒绝授权 | 返回应用，允许用户主动重新发起；不要循环弹出 |
invalid_client | client_id、客户端类型、Secret 或客户端停用 | 检查配置；轮换过 Secret 时更新服务端 |
invalid_grant | 授权码过期或已用、verifier 不匹配、刷新令牌已消费 | 重新授权或使用本次刷新返回的新令牌 |
invalid_scope | 请求超出客户端已批准范围 | 缩小请求范围；已签发应用需调整权限时联系平台处理 |
invalid_request | 缺少必填参数、编码或请求格式错误 | 对照端点逐项检查，不重复发送同样的请求 |
授权码有效期为 5 分钟且只能使用一次。收到回调后，先验证 state；同一授权尝试使用同一份 verifier，不能在回调时重新生成。
Refresh Token 会轮换。对同一账户和客户端串行刷新，并原子保存新令牌；旧值不能在多个请求中并发复用。Access Token 有效期使用返回的 expires_in，不要硬编码固定小时数。
OpenAPI
| 结果 | 检查与处理 |
|---|---|
HTTP 401 / invalid_token | 确认发送的是 OAuth Access Token；检查过期、账户和客户端状态 |
HTTP 403 / insufficient_scope | 检查已批准与本次实际授权 Scope，以及是否错误使用客户端令牌代替用户令牌 |
merchant_inactive | 检查绑定商户是否仍处于启用状态 |
| HTTP 404 | 核对路径、编号和授权用户/商户归属；不要据此判断其他用户的资源是否存在 |
| HTTP 400 | 检查 JSON、必填字段、数量和内容类型 |
| HTTP 422 | 请求格式可解析，但库存、限购、渠道或其他业务条件未满足 |
| HTTP 5xx 或网络超时 | 保存业务上下文，先确认上次写操作结果，再决定是否重试 |
订单创建和支付的超时尤其不能盲目重放。查询类请求可采用有限次数、逐步增加间隔的重试；写请求需要自己的防重复提交策略。
通用商户收款
client_credentials_required 表示本接口要求商户服务端令牌，不能使用买家的用户授权令牌。invalid_return_url 返回 HTTP 400，附 field: "return_url" 和中文 error_description；检查 HTTPS、长度和非法字符。payment_conflict 可能是同键参数（包括返回地址）变化；超时重试须使用原键及原参数。merchant_fee_funding_unavailable 需核对费率、钱包和已授权额度。
provider_result_pending 即使返回 HTTP 202 也不是成功付款。买家已返回收银台但尚未回到商户时，先查 status；异步未决须等待核验。返回地址仅由建单服务端提供，浏览器参数不能覆盖。所有字段、状态与限流见 通用商户收款。
invalid_expires_in 表示有效期须为 60～7200 秒的整数，省略时默认 30 分钟。支付期限固定，不能通过刷新或幂等重试延长。410 payment_expired 只禁止继续发起支付，不禁止查询；review 表示到期后结果仍待核对，应保留原单继续对账，不要直接换键重建。
通知未收到时，查询原收款单，并查看 /merchant-payments/{order_no}/notifications 的投递结果。修复接收端后，可用补发接口重新排队 failed 通知。验签使用原始请求体与 notify_secret，时间戳允许偏差 5 分钟；返回 2xx 前先可靠保存通知。按通知事件号去重，并用 status_version 防止乱序覆盖。
错误响应不全是同一个结构
OAuth 错误包含 error、error_description。部分业务错误还包含数值 code、error_details 或 error_uri。按 HTTP 状态与字段含义处理，忽略未知字段，不要依赖某一句中文错误文案做程序分支。
API 返回 HTML 时，先检查是否误用了文档站地址、网页授权地址或错误的代理前缀。
回调和 SDK 常见误区
生产回调必须使用 HTTPS，开发可用 HTTP localhost 或 127.0.0.1。端口、路径和尾斜杠不同都可能导致精确匹配失败。
当前公开路由没有提供标准 OIDC Discovery / JWKS 端点。不要只填 issuer 就假定通用 OIDC SDK 能自动发现所有配置；接入前确认令牌验证方式，不能跳过签名验证。基础身份接入可使用 Access Token 调用 /oauth/userinfo 获取主体。
反馈给平台时提供什么
提供客户端编号、发生时间与时区、接口方法和路径、HTTP 状态、脱敏错误响应，以及相关订单号。不要提供 Secret、Token、授权码或 verifier。普通账户与支付问题的反馈方式见通知与问题反馈。