跳转到主要内容
有效的错误处理对于构建与 Localpayment API 的稳健集成至关重要。了解不同的错误类型及其对应的错误代码将有助于您快速诊断问题并实施相应的解决方案。 我们通过标准化的 HTTP 状态码和详细的错误响应提供全面的错误处理机制。本指南将向您展示如何有效地处理错误,从而构建更具弹性和用户友好的集成方案。

概述

妥善处理错误对于创建可靠的支付集成至关重要。Localpayment 在所有 API endpoint 中使用一致的错误处理机制,帮助您快速识别和解决问题。

标准化代码

所有 API endpoint 和支付方式的错误代码一致

详细信息

包含具体错误详情的易于理解的描述

最佳实践

处理生产环境中错误的成熟策略

HTTP响应代码

Localpayment 使用标准的 HTTP 状态代码来指示 API 请求的成功或失败:​

错误响应结构

当发生错误时,Localpayment 会返回一个包含详细错误信息的 JSON 对象:

错误响应字段


内部状态代码参考

虽然 Localpayment 使用标准 HTTP 代码表示请求级别的状态,但 status.code 和 errors[].code 字段提供了更细粒度的业务逻辑和处理状态。

常见错误场景

身份验证错误

解决方案请检查您的 API 凭据并确保您的访问令牌有效。如有需要,请使用令牌刷新 endpoint。

验证错误

解决方案请查看 errors 数组以了解具体的字段验证问题。请查阅 API 文档了解必填字段和格式规范。

业务逻辑错误

解决方案这些错误需要企业层面解决。请检查账户余额、交易限额,或联系客服了解具体限制。

错误处理的最佳实践

专业提示从一开始就实施结构化日志记录。包含关联 ID、错误代码和上下文信息,以便在生产环境中出现问题时能够更轻松地进行调试。

1.实施全面日志记录

  1. 用户友好的错误信息

创建从技术错误代码到用户友好消息的映射:

  1. 指数退避重试机制

  1. 断路器模式

安装断路器以防止连锁故障:

后续步骤

API 参考

完整的错误代码列表及详细说明

测试指南

学习如何在沙箱中测试错误场景

支持联系方式

获取针对特定错误场景的帮助
最后修改于 2026年11月10日