错误码
本文档提供 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..."
}
}
}处理建议:
同步系统时钟
检查签名算法实现
确认请求体格式一致
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"
}
}
}处理建议:
重试请求 (使用指数退避)
如果持续失败,联系技术支持并提供
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,我们将快速定位问题。
相关文档
文档版本: v1.0.0 最后更新: 2025-10-07 维护: Zanbara API Team
Last updated