错误码

本文档提供 Zanbara API 完整的错误码列表、错误说明以及处理建议,帮助您快速诊断和解决问题。

错误响应格式

所有错误响应遵循统一格式:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "field": "optional_field_name",
    "details": {}
  },
  "timestamp": 1696752000000
}

字段说明:

• code: 机器可读的错误代码,用于程序化处理

• message: 人类可读的错误描述

• field: (可选) 导致错误的请求字段名

• details: (可选) 额外的错误详情

HTTP 状态码

Zanbara API 使用标准 HTTP 状态码:

状态码	含义	说明
200	OK	请求成功
201	Created	资源创建成功
400	Bad Request	请求参数错误
401	Unauthorized	认证失败或 Token 无效
403	Forbidden	权限不足
404	Not Found	资源不存在
429	Too Many Requests	超过速率限制
500	Internal Server Error	服务器内部错误
503	Service Unavailable	服务暂时不可用

认证相关错误 (1xxx)

1001 - AUTHENTICATION_FAILED

说明: JWT Token 认证失败

常见原因:

• Token 已过期

• Token 签名无效

• Token 格式错误

• 缺少 Authorization 请求头

示例:

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Invalid or expired JWT token"
  }
}

处理建议:

if (error.code === 'AUTHENTICATION_FAILED') {
  // 重新获取 Token
  token = await getNewToken();
  // 重试请求
  return retryRequest();
}

1002 - INVALID_API_KEY

说明: API Key 无效或已被禁用

常见原因:

• API Key 格式错误

• API Key 已被删除

• API Key 已被禁用

示例:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key not found or has been disabled"
  }
}

处理建议: 检查 API Key 配置,必要时生成新的 API Key

1003 - INVALID_SIGNATURE

说明: 请求签名验证失败

常见原因:

• 签名算法实现错误

• 时间戳与服务器时间相差超过 5 秒

• 请求体与签名不匹配

示例:

{
  "success": false,
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Request signature verification failed",
    "details": {
      "expected": "abc123...",
      "received": "def456..."
    }
  }
}

处理建议:

1. 同步系统时钟

2. 检查签名算法实现

3. 确认请求体格式一致

1004 - INSUFFICIENT_PERMISSIONS

说明: API Key 权限不足

常见原因:

• 使用只读 Key 执行交易操作

• 使用交易 Key 执行提现操作

示例:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "API Key does not have permission for this operation",
    "details": {
      "required": "trading",
      "actual": "readonly"
    }
  }
}

处理建议: 使用具有相应权限的 API Key

1005 - IP_NOT_WHITELISTED

说明: 请求 IP 不在白名单中

示例:

{
  "success": false,
  "error": {
    "code": "IP_NOT_WHITELISTED",
    "message": "Request IP 203.0.113.50 is not in the whitelist",
    "details": {
      "ip": "203.0.113.50"
    }
  }
}

处理建议: 在 API Key 设置中添加 IP 到白名单

请求参数错误 (2xxx)

2001 - INVALID_INPUT

说明: 请求参数格式或类型错误

示例:

{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid parameter: quantity must be a positive decimal",
    "field": "quantity"
  }
}

处理建议: 检查参数类型和格式

2002 - MISSING_REQUIRED_FIELD

说明: 缺少必需的请求字段

示例:

{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Required field 'symbol' is missing",
    "field": "symbol"
  }
}

处理建议: 补充缺失的必需字段

2003 - INVALID_SYMBOL

说明: 交易对不存在或格式错误

示例:

{
  "success": false,
  "error": {
    "code": "INVALID_SYMBOL",
    "message": "Symbol 'INVALID-PERP' does not exist",
    "field": "symbol"
  }
}

处理建议: 使用 GET /v1/market/symbols 查询有效交易对列表

2004 - INVALID_SIDE

说明: 订单方向无效

有效值: buy, sell

示例:

{
  "success": false,
  "error": {
    "code": "INVALID_SIDE",
    "message": "Invalid order side 'long'. Valid values: buy, sell",
    "field": "side"
  }
}

2005 - INVALID_ORDER_TYPE

说明: 订单类型无效

有效值: limit, market, stop_limit, stop_market, post_only, iceberg

示例:

{
  "success": false,
  "error": {
    "code": "INVALID_ORDER_TYPE",
    "message": "Invalid order type 'unknown'",
    "field": "type"
  }
}

2006 - INVALID_QUANTITY

说明: 订单数量无效

常见原因:

• 数量为负数或零

• 数量小于最小订单量

• 数量超过最大订单量

• 数量精度超过限制

示例:

{
  "success": false,
  "error": {
    "code": "INVALID_QUANTITY",
    "message": "Quantity 0.001 is below minimum order size 0.01",
    "field": "quantity",
    "details": {
      "min": "0.01",
      "max": "10000",
      "provided": "0.001"
    }
  }
}

2007 - INVALID_PRICE

说明: 订单价格无效

常见原因:

• 价格为负数或零

• 价格偏离市场价过大

• 价格精度超过限制

示例:

{
  "success": false,
  "error": {
    "code": "INVALID_PRICE",
    "message": "Price 200.5 deviates more than 10% from mark price 150.0",
    "field": "price",
    "details": {
      "mark_price": "150.0",
      "provided_price": "200.5",
      "max_deviation": "10%"
    }
  }
}

2008 - INVALID_LEVERAGE

说明: 杠杆倍数无效

示例:

{
  "success": false,
  "error": {
    "code": "INVALID_LEVERAGE",
    "message": "Leverage 25 exceeds maximum allowed leverage 20 for SOL-PERP",
    "field": "leverage",
    "details": {
      "symbol": "SOL-PERP",
      "max_leverage": 20,
      "provided": 25
    }
  }
}

2009 - INVALID_TIME_IN_FORCE

说明: 订单时间有效性参数无效

有效值: GTC, IOC, FOK, GTT

业务逻辑错误 (3xxx)

3001 - INSUFFICIENT_BALANCE

说明: 账户余额不足

示例:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance: available=100.00 USDC, required=150.00 USDC",
    "details": {
      "asset": "USDC",
      "available": "100.00",
      "required": "150.00"
    }
  }
}

处理建议: 充值或减少订单金额

3002 - ORDER_NOT_FOUND

说明: 订单不存在

常见原因:

• 订单 ID 错误

• 订单已被撤销或成交

• 查询他人的订单

示例:

{
  "success": false,
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order 123e4567-e89b-12d3-a456-426614174000 not found"
  }
}

3003 - POSITION_NOT_FOUND

说明: 仓位不存在

示例:

{
  "success": false,
  "error": {
    "code": "POSITION_NOT_FOUND",
    "message": "No position found for symbol SOL-PERP",
    "details": {
      "symbol": "SOL-PERP"
    }
  }
}

3004 - ORDER_ALREADY_FILLED

说明: 订单已成交,无法撤销

示例:

{
  "success": false,
  "error": {
    "code": "ORDER_ALREADY_FILLED",
    "message": "Order is already filled and cannot be cancelled",
    "details": {
      "order_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "filled"
    }
  }
}

3005 - POSITION_SIZE_EXCEEDED

说明: 超过最大仓位限制

示例:

{
  "success": false,
  "error": {
    "code": "POSITION_SIZE_EXCEEDED",
    "message": "Position size would exceed maximum allowed",
    "details": {
      "symbol": "SOL-PERP",
      "current_size": "1000",
      "order_size": "500",
      "max_position": "1200"
    }
  }
}

3006 - LIQUIDATION_RISK

说明: 操作会导致清算风险过高

示例:

{
  "success": false,
  "error": {
    "code": "LIQUIDATION_RISK",
    "message": "Operation would result in liquidation risk above threshold",
    "details": {
      "current_margin_ratio": "15%",
      "maintenance_margin": "5%",
      "after_operation": "3%"
    }
  }
}

处理建议: 降低杠杆或增加保证金

3007 - MARKET_CLOSED

说明: 市场已关闭

示例:

{
  "success": false,
  "error": {
    "code": "MARKET_CLOSED",
    "message": "Market SOL-PERP is temporarily closed for trading",
    "details": {
      "symbol": "SOL-PERP",
      "reason": "maintenance",
      "reopen_at": 1696752000000
    }
  }
}

3008 - DUPLICATE_ORDER

说明: 重复的 client_order_id

示例:

{
  "success": false,
  "error": {
    "code": "DUPLICATE_ORDER",
    "message": "Order with client_order_id 'unique-123' already exists",
    "details": {
      "existing_order_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}

说明: 这是幂等性保护,如果确实是重复请求,可以使用返回的现有订单

3009 - SELF_TRADE_PREVENTION

说明: 触发自成交预防机制

示例:

{
  "success": false,
  "error": {
    "code": "SELF_TRADE_PREVENTION",
    "message": "Order would match with your own order and has been rejected",
    "details": {
      "matching_order_id": "456e4567-e89b-12d3-a456-426614174000"
    }
  }
}

3010 - PRICE_DEVIATION_EXCEEDED

说明: 价格偏离市场价过大

示例:

{
  "success": false,
  "error": {
    "code": "PRICE_DEVIATION_EXCEEDED",
    "message": "Price deviates more than 10% from current mark price",
    "details": {
      "mark_price": "150.0",
      "order_price": "200.0",
      "max_deviation": "10%"
    }
  }
}

处理建议: 调整价格或使用市价单

速率限制错误 (4xxx)

4001 - RATE_LIMIT_EXCEEDED

说明: 超过 API 速率限制

示例:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded: 120 requests per minute",
    "details": {
      "limit": 120,
      "retry_after": 45
    }
  }
}

HTTP 响应头:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Reset: 1696752060

处理建议: 参考 速率限制文档

系统错误 (5xxx)

5001 - INTERNAL_ERROR

说明: 服务器内部错误

示例:

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred. Please try again later.",
    "details": {
      "request_id": "req_abc123"
    }
  }
}

处理建议:

1. 重试请求 (使用指数退避)

2. 如果持续失败,联系技术支持并提供 request_id

5002 - SERVICE_UNAVAILABLE

说明: 服务暂时不可用

常见原因:

• 系统维护

• 服务过载

• 网络故障

示例:

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service is temporarily unavailable due to maintenance",
    "details": {
      "estimated_restore": 1696752000000
    }
  }
}

HTTP 状态码: 503

5003 - DATABASE_ERROR

说明: 数据库操作错误

示例:

{
  "success": false,
  "error": {
    "code": "DATABASE_ERROR",
    "message": "Database operation failed. Please try again.",
    "details": {
      "request_id": "req_abc123"
    }
  }
}

5004 - MATCHING_ENGINE_ERROR

说明: 撮合引擎错误

示例:

{
  "success": false,
  "error": {
    "code": "MATCHING_ENGINE_ERROR",
    "message": "Order matching service is experiencing issues",
    "details": {
      "request_id": "req_abc123"
    }
  }
}

5005 - SETTLEMENT_FAILED

说明: 链上结算失败

示例:

{
  "success": false,
  "error": {
    "code": "SETTLEMENT_FAILED",
    "message": "Blockchain settlement failed. Transaction will be retried.",
    "details": {
      "tx_signature": "5J7Xg...",
      "retry_count": 2
    }
  }
}

说明: 系统会自动重试,通常无需用户介入

错误处理最佳实践

1. 按错误码分类处理

async function handleAPIError(error) {
  const { code } = error;

  // 认证错误 - 重新获取 Token
  if (code.startsWith('1')) {
    token = await refreshToken();
    return retryRequest();
  }

  // 参数错误 - 检查输入
  if (code.startsWith('2')) {
    console.error('Invalid parameters:', error.message);
    throw error;
  }

  // 业务错误 - 根据具体错误处理
  if (code.startsWith('3')) {
    switch (code) {
      case 'INSUFFICIENT_BALANCE':
        return handleInsufficientBalance(error);
      case 'ORDER_NOT_FOUND':
        return handleOrderNotFound(error);
      default:
        throw error;
    }
  }

  // 速率限制 - 等待后重试
  if (code.startsWith('4')) {
    const retryAfter = error.details.retry_after || 60;
    await sleep(retryAfter * 1000);
    return retryRequest();
  }

  // 系统错误 - 重试或联系支持
  if (code.startsWith('5')) {
    return retryWithBackoff(3);
  }
}

2. 实现重试机制

async function retryWithBackoff(maxRetries, baseDelay = 1000) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await executeRequest();
    } catch (error) {
      if (i === maxRetries - 1) throw error;

      // 仅对临时错误重试
      if (!isRetryableError(error)) throw error;

      // 指数退避
      const delay = baseDelay * Math.pow(2, i);
      await sleep(delay);
    }
  }
}

function isRetryableError(error) {
  const retryableCodes = [
    'RATE_LIMIT_EXCEEDED',
    'INTERNAL_ERROR',
    'SERVICE_UNAVAILABLE',
    'DATABASE_ERROR',
    'MATCHING_ENGINE_ERROR'
  ];

  return retryableCodes.includes(error.code);
}

3. 记录错误日志

async function callAPIWithLogging(endpoint, options) {
  const startTime = Date.now();

  try {
    const response = await fetch(endpoint, options);
    const data = await response.json();

    if (!data.success) {
      logError({
        endpoint,
        error: data.error,
        duration: Date.now() - startTime,
        timestamp: new Date().toISOString()
      });
    }

    return data;
  } catch (error) {
    logError({
      endpoint,
      error: {
        code: 'NETWORK_ERROR',
        message: error.message
      },
      duration: Date.now() - startTime,
      timestamp: new Date().toISOString()
    });

    throw error;
  }
}

4. 用户友好的错误提示

const ERROR_MESSAGES = {
  INSUFFICIENT_BALANCE: '余额不足,请先充值',
  INVALID_QUANTITY: '订单数量无效,请检查输入',
  POSITION_SIZE_EXCEEDED: '超过最大仓位限制',
  RATE_LIMIT_EXCEEDED: '操作过于频繁,请稍后再试',
  INTERNAL_ERROR: '系统错误,请稍后重试'
};

function getUserFriendlyMessage(errorCode) {
  return ERROR_MESSAGES[errorCode] || '操作失败,请重试';
}

调试工具

错误代码查询

使用我们的在线工具快速查询错误代码:

https://docs.zanbarax.com/error-lookup?code=3001

错误统计

在 API 管理页面查看您的错误统计:

• 按错误码分组

• 按时间趋势

• 按端点分类

请求日志

每个错误响应都包含 request_id,用于在支持工单中追踪:

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred",
    "details": {
      "request_id": "req_20251007_abc123"
    }
  }
}

联系支持时请提供 request_id,我们将快速定位问题。

相关文档

• API 概述 - API 基础信息

• 认证机制 - JWT Token 和签名

• 速率限制 - 请求频率限制

• 交易 API - 下单、撤单接口

---

文档版本: v1.0.0 最后更新: 2025-10-07 维护: Zanbara API Team