错误码

错误响应格式

兼容接口（GodaPay-compat）的响应用顶层 code 表示成败：code: 0 为成功，非 0 即错误。

{
  "code": 1103,
  "message": "Amount must be between 10 and 1000000"
}

code 是数字（稳定，用于程序匹配），message 是英文说明（文案可能迭代）。

HTTP 状态码

状态码	含义
200	OK — 请求成功
201	Created — 资源创建成功
400	Bad Request — 参数校验失败或业务规则不满足
401	Unauthorized — 认证失败
403	Forbidden — 已认证但无权限
404	Not Found — 资源不存在
429	Too Many Requests — 超过速率限制
500	Internal Server Error — 服务端错误

错误码

认证类（1000–1099）

代码	名称	HTTP	触发条件
1001	INVALID_API_KEY	401	API Key 不存在或与 Merchant ID 不匹配
1002	INVALID_SIGNATURE	401	请求体 signature 校验失败
1004	MISSING_AUTH_HEADER	401	缺少 merchantId 或 signature
1008	ACCOUNT_DISABLED	403	商户账号未激活或被冻结
1010	FORBIDDEN	403	资源不属于当前商户
1011	UNAUTHORIZED	401	一般性未认证

校验类（1100–1199）

代码	名称	HTTP	触发条件
1100	VALIDATION_ERROR	400	一般字段校验失败
1101	MISSING_REQUIRED_FIELD	400	缺少必填字段
1102	INVALID_FIELD_FORMAT	400	字段格式不合法（含手机号）
1103	INVALID_AMOUNT	400	金额超出合法范围
1104	INVALID_CHANNEL	400	channel 不是支持的枚举
1105	INVALID_ORDER_TYPE	400	订单类型错误
1106	INVALID_STATUS	400	状态值不合法

业务类（1200–1299）

代码	名称	HTTP	触发条件
1200	ORDER_NOT_FOUND	404	订单 ID 不存在
1201	DUPLICATE_ORDER	400	同一商户下 merchant_order_id 重复
1202	ORDER_EXPIRED	400	订单已过期
1203	INSUFFICIENT_BALANCE	400	商户余额不足以支付该笔付款
1205	MERCHANT_NOT_FOUND	404	商户记录不存在
1209	INVALID_ORDER_STATUS	400	当前订单状态不允许该操作

速率限制（1300–1399）

代码	名称	HTTP	触发条件
1300	RATE_LIMIT_EXCEEDED	429	超过商户每分钟速率上限
1301	TOO_MANY_REQUESTS	429	一般限流（IP 级或会话级）

429 响应携带标准的 Retry-After 响应头与 error.details.retry_after_seconds，详见 速率限制。

服务端错误（1400–1499）

代码	名称	HTTP	触发条件
1400	INTERNAL_SERVER_ERROR	500	服务端通用错误
1403	EXTERNAL_SERVICE_ERROR	502	上游服务错误，请重试

资源未找到（1500–1599）

代码	名称	HTTP	触发条件
1500	RESOURCE_NOT_FOUND	404	通用未找到
1501	ENDPOINT_NOT_FOUND	404	路由不存在

错误处理示例

Node.js

async function createOrder(params) {
  const response = await sendSigned('/pay/order/create', params); // 见代码示例
  const result = await response.json();

  if (result.code !== 0) {
    const { code, message } = result;
    switch (code) {
      case 1002: throw new Error(`签名错误：${message}`);
      case 1103: throw new Error(`金额超出范围：${message}`);
      case 1201: throw new Error(`orderNo 已存在`);
      case 1203: throw new Error(`商户余额不足`);
      case 1300:
      case 1301: {
        const retryAfter = response.headers.get('retry-after') || 60;
        throw new Error(`触发限流，请 ${retryAfter} 秒后重试`);
      }
      default: throw new Error(`[${code}] ${message}`);
    }
  }

  return result.data;
}

Python

def create_order(params):
    response = send_signed('/pay/order/create', params)  # 见代码示例
    result = response.json()

    code = result.get('code')
    if code != 0:
        message = result.get('message', '')
        if code == 1002:
            raise Exception(f"签名错误：{message}")
        if code == 1103:
            raise Exception(f"金额超出范围：{message}")
        if code == 1201:
            raise Exception("orderNo 已存在")
        if code == 1203:
            raise Exception("商户余额不足")
        if code in (1300, 1301):
            retry = response.headers.get('retry-after') or 60
            raise Exception(f"触发限流，请 {retry} 秒后重试")
        raise Exception(f"[{code}] {message}")

    return result['data']

调试建议

1. 关注 error.code 数值：服务器文案会迭代，数字码稳定。
2. 保留 meta.requestId：联系技术支持时附上该值便于定位。
3. 签名相关错误优先排查：1002 与 1003 占绝大多数支持工单，参考 常见签名错误。
4. 限流时遵守 Retry-After：硬编码固定回退会持续触发 1300。