错误处理

所有 Lampay API 响应 -- 无论成功还是失败 -- 都遵循统一的信封格式。本页介绍响应结构、HTTP 状态码规范以及按业务域组织的完整错误码目录。

响应信封

Lampay API 的每个响应都封装在带有元数据字段的标准信封中。

成功响应

200成功

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "transferId": "txn_789xyz",
    "status": "COMPLETED",
    "amount": "100.00",
    "currency": "USD"
  }
}

错误响应

400错误

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": false,
  "code": "T1007",
  "message": "INVALID_AMOUNT",
  "data": null
}

信封字段

字段	类型	说明
version	string	API 版本（如 1.3.0）
timestamp	long	响应时间戳，毫秒级 epoch 时间
success	boolean	成功操作为 true，错误为 false
code	string	机器可读的结果码。2xxx = 成功，带域前缀的码 = 错误
message	string	人类可读的结果描述
data	object / null	成功时为响应数据载荷；错误时始终为 null

提示 程序化错误处理

始终先检查 success 字段。当 success 为 false 时，使用 code 字段进行程序化处理（如重试逻辑、用户提示消息）。message 字段仅供参考，可能在 API 版本间变化 -- 不要程序化解析它。

---

HTTP 状态码

Lampay API 使用标准 HTTP 状态码。以下表列出了您可能遇到的所有状态码：

状态码	含义	返回场景
200	OK	请求成功，响应体包含结果
201	Created	新资源创建成功
204	No Content	请求成功，无响应体（如 DELETE 操作）
400	Bad Request	参数校验错误、无效参数或业务规则违反
401	Unauthorized	缺少或无效的认证信息（API 密钥错误、签名不匹配、时间戳过期）
403	Forbidden	认证成功但调用方缺少此操作的权限
404	Not Found	请求的资源不存在
409	Conflict	资源已存在或操作与当前状态冲突
429	Too Many Requests	超出速率限制 -- 等待后重试
500	Internal Server Error	服务器内部错误 -- 如持续出现请联系支持

---

错误码目录

错误码由域前缀加数字标识组成。前缀标识生成错误的模块；完整编码唯一标识错误条件。

S -- 系统 / 基础设施

可在任何端点上出现的通用系统级错误。

错误码	名称	HTTP	说明
S001	INTERNAL_ERROR	500	服务器内部错误。如持续出现请联系支持。
S002	SERVICE_UNAVAILABLE	503	依赖服务不可用。请在短暂延迟后重试。
S003	TIMEOUT	504	操作超时。请求可能已被处理也可能未被处理。
S004	INVALID_REQUEST	400	请求格式错误（如无效的 JSON 语法）。
S005	UNAUTHORIZED	401	需要认证但未提供。
S006	FORBIDDEN	403	访问被拒绝。调用方不具备所需角色或权限。
S007	NOT_FOUND	404	请求的资源未找到。
S011	VALIDATION_ERROR	400	一个或多个请求字段未通过校验。
S012	INVALID_PARAMETER	400	参数值无效（类型错误、超出范围等）。
S013	MISSING_PARAMETER	400	请求缺少必填参数。
S031	DATA_NOT_FOUND	404	数据库中未找到请求的数据记录。
S032	DATA_ALREADY_EXISTS	409	具有相同唯一键的记录已存在。
S034	CONCURRENT_MODIFICATION	409	乐观锁冲突。另一个操作并发修改了此资源。请重试。

W -- 钱包

钱包账户和余额操作的错误。

错误码	名称	HTTP	说明
W1001	ACCOUNT_NOT_FOUND	404	钱包账户未找到。
W1002	ACCOUNT_INACTIVE	400	钱包账户未激活。请先激活再执行操作。
W1003	ACCOUNT_FROZEN	400	钱包账户已冻结。请联系管理员。
W1004	ACCOUNT_ALREADY_EXISTS	409	具有此身份的钱包账户已存在。
W3001	INSUFFICIENT_BALANCE	400	钱包余额不足以完成此操作。
W3003	INSUFFICIENT_AVAILABLE	400	可用余额（扣除冻结部分）不足。
W3005	OPTIMISTIC_LOCK_CONFLICT	409	检测到钱包余额的并发修改。请重试操作。
W5005	CURRENCY_NOT_SUPPORTED	400	此钱包不支持指定的币种。
W9004	MISSING_WORKSPACE_CONTEXT	401	缺少工作空间上下文。请确保 API 密钥已关联到工作空间。

T -- 转账

转账创建和处理的错误。

错误码	名称	HTTP	说明
T1001	SOURCE_WALLET_NOT_FOUND	404	源钱包未找到。
T1002	TARGET_WALLET_NOT_FOUND	404	目标钱包未找到。
T1005	CURRENCY_MISMATCH	400	源钱包和目标钱包使用不同的币种。
T1006	SAME_WALLET_TRANSFER	400	不能向同一钱包转账。
T1007	INVALID_AMOUNT	400	转账金额必须为正数。
T1008	INSUFFICIENT_BALANCE	400	源钱包余额不足。
T1020	ORDER_NOT_FOUND	404	转账订单未找到。
T1023	DUPLICATE_REQUEST	409	具有此幂等键的转账已被处理。
T1040	EXECUTION_FAILED	500	转账执行失败。资金未被转移。
T1044	TARIFF_NOT_CONFIGURED	400	钱包费率（手续费方案）未配置。请联系管理员。

GA -- 网关认证

API 网关认证流水线的错误。完整的验证流水线请参阅 HMAC 认证。

错误码	名称	HTTP	说明
GA2001	API_KEY_REQUIRED	401	缺少 X-Api-Key 头。
GA2002	SIGNATURE_REQUIRED	401	缺少 X-Signature 头。
GA2011	API_KEY_INVALID	401	API 密钥无效或未找到。
GA2012	SIGNATURE_INVALID	401	签名验证失败。
GA2013	TIMESTAMP_EXPIRED	401	请求时间戳超出 60 秒窗口。
GA2021	API_KEY_DISABLED	403	API 密钥已被禁用。
GA2022	IP_NOT_ALLOWED	403	客户端 IP 不在白名单中。
GA2024	SCOPE_DENIED	403	API 密钥缺少所需权限范围。
GA2032	WORKSPACE_NOT_FOUND	404	工作空间未找到。
GA2034	WORKSPACE_NOT_MEMBER	403	用户不是工作空间成员。

---

错误处理最佳实践

提示 重试策略

对于 5xx 错误和 429（速率限制），实施带抖动的指数退避。初始延迟 1 秒，每次重试加倍，并添加随机抖动以避免惊群效应。最多重试 3-5 次。

提示 幂等性

对于创建资源的 POST 操作，使用幂等键。如果请求因网络错误失败而您重试，幂等键可防止重复创建。T1023（DUPLICATE_REQUEST）响应意味着您的原始请求已成功处理。

提示 用户提示消息

在您的应用中将错误码映射为用户友好的消息。不要向终端用户显示原始错误码或 message 字段 -- 它们面向开发者。构建一个翻译层，将类似 W3001 的错误码转换为"余额不足，无法完成此转账"之类的消息。

提示 日志记录

对每个错误记录完整的响应信封（包括 code、message 和 timestamp）。timestamp 字段有助于在与 Lampay 支持团队合作时将客户端错误与服务端日志进行关联。