跳到主要内容

错误码

当 GStable API 处理请求失败时，即使 HTTP 状态码返回 200 OK，响应体中的 code 字段也会包含一个非 0 的错误代码。

本页列出了所有预定义的业务错误码，帮助你通过程序逻辑处理异常情况。

错误响应结构​

正如 API 介绍 中所述，你需要检查 JSON 响应中的 code。

{
  "code": 100203,
  "message": "Session is expired",
  "data": null
}

动态错误消息​

message 字段通常为固定的错误描述，但在某些验证错误中，它可能会包含具体的上下文信息，格式为 错误描述: 具体信息。

例如：

  • 标准消息："Invalid field format"
  • 详细消息："Invalid field format: email is required"
最佳实践

不要通过解析 message 字符串来编写业务逻辑，因为文案可能会调整。请始终依据 code (错误码) 来进行程序流控制。

1. 支付流程错误 (Payment Flow)​

涉及支付链接 (Payment Link)、结账会话 (Checkout Session) 和商品 (Product) 的业务逻辑错误。

支付链接 (1001XX)​

错误码错误消息 (Message)描述与原因
100101Payment link not found指定的 Payment Link ID 不存在。
100102Payment link is archived该支付链接已被归档，无法再次访问或修改。
100103Payment link is not active该支付链接已被禁用 (Disabled)。
100104Invalid payment link version请求的链接版本号不支持。

结账会话 (1002XX)​

错误码错误消息 (Message)描述与原因
100201Session not found指定的 Checkout Session ID 不存在。
100202Session client key is invalid提供的 Client Key 验证失败。
100203Session is expired会话已超过有效期（默认 30 分钟），无法继续支付。
100204Session is paid该会话已完成支付，不能重复支付。
100205Session is cancelled用户或商户主动取消了该会话。
100206Session payer mismatch实际支付者与会话预设的支付者信息不匹配。
100207Receipt not found无法找到该会话对应的交易回单。
100208Payment session is not completed尝试查询结果时，会话尚未完成支付。
100209Onchain transaction not found无法在区块链上追踪到关联的交易哈希。
100210Session lock failed会话当前被其他进程锁定，请稍后重试。
100211Session is not cancellable会话在当前状态下无法被取消。

商品管理 (1003XX)​

错误码错误消息 (Message)描述与原因
100301Product not found指定的 Product ID 不存在。
100302Product partial missing批量操作中部分商品 ID 不存在。
100303Product partially unavailable批量操作中部分商品状态不可用。
100304Product is not active商品未处于激活状态，无法用于创建链接或会话。
100305Product has been used商品已被关联使用，无法执行某些特定修改。
100306Product has been removed商品已被逻辑删除。

2. 集成与配置错误 (Integration)​

涉及 API Key 鉴权和 Webhook 配置的错误。

API Key (2001XX)​

错误码错误消息 (Message)描述与原因
200101API key not found请求 Header 中未提供 Key 或 Key 不存在。
200102API key is rotating该 Key 正在轮换中，暂时不可用。
200103API key is revoked该 Key 已被撤销，请生成新的 Key。
200104Invalid expired timeKey 的过期时间设置无效。
200105API key limit reached账户生成的 API Key 数量已达上限。
200106API key is not active该 API Key 未处于激活状态。

Webhook (2002XX)​

错误码错误消息 (Message)描述与原因
200201Webhook not found指定的 Webhook ID 不存在。
200202Failed to ping webhook测试 Webhook 发送失败，请检查目标 URL 是否可达。
200203Webhook limit reachedWebhook Endpoint 创建数量已达上限。

3. 商户与账户错误 (User & Account)​

涉及商户登录、账户状态及报表查询的错误。

认证与状态 (3001XX - 3002XX)​

错误码错误消息 (Message)描述与原因
300101Invalid sign in登录凭证无效。
300102Authentication check failed二次验证或安全检查失败。
300201User not found用户不存在。
300202User is blocked用户已被封禁，无法操作。

账户配置 (3003XX)​

错误码错误消息 (Message)描述与原因
300301Account is not found商户账户不存在。
300302Account is removed商户账户已被移除。
300303Account address already exists尝试添加的收款地址已存在。
300304Unsupported settlement token of the account账户不支持该结算代币配置。
300305Account count limit reached账户数量已达到系统上限。
300306At least one account is required操作失败，因为必须保留至少一个账户。

报表查询 (3004XX)​

错误码错误消息 (Message)描述与原因
300401Report not found请求的报表不存在。
300402Report is duplicated重复创建相同的报表任务。
300403Report has no data in the time range指定时间范围内没有数据可生成报表。
300404Report data count is too large请求的数据量过大，请缩短查询时间范围。

4. 通用与验证错误 (Common)​

请求参数格式校验及不支持的通道错误。

错误码错误消息 (Message)描述与原因
400101Invalid field format参数格式错误（如非法的 email、URL 或数字）。
400201Unsupported currency请求的币种不在 GStable 支持列表中。
400202Unsupported channel请求的区块链通道或网络不支持。
400203Settlement capabilities not found系统无法找到适用于此配置的结算能力。
400301Stat not found请求的统计数据不存在。

5. 平台系统错误 (Platform)​

涉及系统限流、数据库及内部异常。

错误码错误消息 (Message)描述与原因
900101Too many requests请求频率超过配额 (QPS 限制)。建议实施退避重试。
900201Failed to create record数据库写入失败。
900202Failed to update record数据库更新失败。
900203Failed to query record数据库查询失败。
900301Image processing failed图片上传或处理失败。
999999Internal system error系统内部未知错误。请联系 GStable 支持团队并提供 Trace ID。