错误码与 SDK 异常

失败时 SDK 抛出 GStableError 或其子类。使用 isGStableError(err) 做类型收窄。

基类

属性	含义
code	数字型业务或传输错误码；-1 常在收到 HTTP 响应前表示网络错误。
message	人类可读说明；不要依赖固定英文文案做分支。

createTypedApiError

当 API 返回信封且 code !== 0 时，HTTP 层调用 createTypedApiError(code, message)：

条件	抛出类型
商品区间 100301–100306	GStableProductError（productErrorCode 与 code 相同）
已知 通用/校验码（SDK 常量中的 400XXX）	GStableCommonError
已知 平台码（900XXX / 999999）	GStablePlatformError
其他	GStableError

商品码（ProductErrorCodes）

常量	值	典型含义
NOT_FOUND	100301	商品 ID 不存在。
PARTIAL_MISSING	100302	批量：部分 ID 缺失。
PARTIALLY_UNAVAILABLE	100303	批量：部分不可用。
NOT_ACTIVE	100304	未激活，无法用于 link/session。
HAS_BEEN_USED	100305	因已被使用而禁止变更。
HAS_BEEN_REMOVED	100306	已逻辑删除。

使用 isProductErrorCode(code)、ProductErrorMessages（仅作文案参考）。

通用码（CommonErrorCodes）

常量	值
INVALID_FIELD_FORMAT	400101
UNSUPPORTED_CURRENCY	400201
UNSUPPORTED_CHANNEL	400202
SETTLEMENT_CAPABILITIES_NOT_FOUND	400203
STAT_NOT_FOUND	400301

平台码（PlatformErrorCodes）

常量	值
TOO_MANY_REQUESTS	900101
FAILED_TO_CREATE_RECORD	900201
FAILED_TO_UPDATE_RECORD	900202
FAILED_TO_QUERY_RECORD	900203
IMAGE_PROCESSING_FAILED	900301
INTERNAL_SYSTEM_ERROR	999999

HTTP / 传输边界情况

• 非 JSON body（HTML、WAF、代理）→ GStableError，带描述性 message（SDK 对 403/401 等有辅助信息）。
• HTTP 200 但 无效信封 → GStableError。

权威分类

完整、权威的表格见主站 API 概览 → Errors：docs.gstable.io。

示例 — 按商品错误分支

import {
  GStableClient,
  isGStableProductError,
  ProductErrorCodes,
} from 'gstable-js';

const client = new GStableClient({ apiKey: process.env.GSTABLE_API_KEY });

try {
  await client.product.remove('prod_xxx');
} catch (e) {
  if (isGStableProductError(e) && e.code === ProductErrorCodes.HAS_BEEN_USED) {
    // 处理「使用中」
  }
  throw e;
}