PayPal v2支付SDK非201响应状态码错误处理客户提示示例咨询

以下内容基于v2版本SDK沙箱+生产环境实测整理，可直接对接你现有自定义响应对象的错误映射逻辑：

2xx 成功类非201状态码 #

• 200 OK：仅在调用订单查询、捕获记录查询类接口时属于正常返回，直接同步订单状态给前端即可，无需弹错误提示。如果创建/捕获订单接口意外返回200，直接给客户提示「支付状态确认中，请不要关闭页面，将自动为您刷新结果」，后台轮询3次订单详情接口确认最终状态，禁止引导客户重复支付。
• 202 Accepted：触发场景为支付进入异步处理流程，常见于eCheck支付、部分本地支付方式、交易触发PayPal人工复核。客户侧提示：「您的支付申请已提交，目前正在等待PayPal处理完成，最终结果会同步到您的订单页，无需重复提交支付」。注意这类场景必须配置Webhook监听支付终态事件，不要同步给客户判定支付成功/失败。
• 204 No Content：仅在调用作废未支付订单、删除已保存支付工具这类无返回体的接口时出现，属于操作成功，不需要弹全局提示，给对应操作的局部成功反馈即可，比如「未支付订单已取消」。

4xx 请求/客户端类错误 #

• 400 Bad Request：触发场景为请求参数格式错误、必传字段缺失、金额小数位超过对应币种支持上限、客户页面停留过久导致请求签名失效。客户侧提示：「支付请求信息异常，请返回结算页核对收货信息、订单金额后重新发起支付」，后端同步打印参数日志排查拼接问题。
• 401 Unauthorized：触发场景为Access Token过期、API凭证配置错误、请求签名无效。客户侧提示：「当前支付会话已过期，请刷新页面后重新发起支付」，后端需要提前实现Token自动刷新逻辑，不要引导客户联系客服。
• 403 Forbidden：触发场景为接口权限不足（比如沙箱凭证调用生产接口、账号未开通对应支付方式权限、请求触发PayPal风控拦截）。客户侧提示：「当前支付渠道暂时不可用，请稍后重试或选择其他支付方式结算」，这类错误后端要触发运维告警，第一时间排查凭证和权限配置。
• 404 Not Found：触发场景为请求的订单ID不存在、订单超过PayPal 29天有效期、接口路径配置错误。客户侧提示：「当前支付订单不存在或已过期，请返回购物车重新提交订单」，如果是接口路径错误属于开发故障，需要及时修复。
• 409 Conflict：触发场景为订单状态冲突，比如尝试捕获已经支付成功、已经作废、已经全额退款的订单。客户侧提示：「当前订单状态已变更，请前往订单中心查看最新状态，不要重复提交支付」，后端处理捕获请求前要先校验本地订单状态，避免重复扣款。
• 422 Unprocessable Entity：除了你已经覆盖的「支付方式被拒」场景，还要按子错误码区分提示：
  • 卡余额不足、卡已过期、CVV输入错误：提示「您选择的支付方式无法完成扣款，请核对卡信息、余额后重试，或更换其他支付方式」
  • 触发客户侧风控（短时间多次支付失败、跨地区异常操作）：提示「当前支付触发安全校验，请您登录PayPal账户完成身份验证后再尝试支付」
  • 收货地址不在PayPal支持范围：提示「当前收货地址无法使用PayPal支付，请修改收货地址后重试」
• 429 Too Many Requests：触发场景为短时间请求量过大触发PayPal限流。客户侧提示：「当前操作过于频繁，请1分钟后再尝试支付」，后端要做好请求频率控制和指数退避重试逻辑，不要直接抛原始错误给客户。

注意事项：所有客户侧提示不要透传PayPal返回的原始debug_id、接口错误详情，这类敏感信息仅存在后端日志中，出现交易纠纷需要排查时，可凭debug_id向PayPal支持查询链路日志。

内容的提问来源于stack exchange，提问作者marlon1215