错误处理

所有 SlaunchX API 响应——无论成功与否——都遵循一致的信封格式。本页记录了响应结构、HTTP 状态码约定以及按领域组织的完整错误码目录。

响应信封

SlaunchX 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 状态码

SlaunchX 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 字段有助于在与 SlaunchX 支持团队合作时，将客户端错误与服务端日志进行关联。

错误处理 ​

响应信封 ​

成功响应 ​

错误响应 ​

信封字段 ​

HTTP 状态码 ​

错误码目录 ​

S -- 系统 / 基础设施 ​

W -- 钱包 ​

T -- 转账 ​

GA -- 网关认证 ​

错误处理最佳实践 ​