错误代码 (Error Codes)

AXBlade API 使用标准的 HTTP 状态码来表示请求的成功或失败，并在响应体中提供具体的错误信息。

响应格式

{
  "error": "ERROR_CODE",
  "message": "Human readable error description",
  "code": 400
}

---

常用 HTTP 状态码

状态码	说明	常见场景
200	OK	请求成功
400	Bad Request	参数错误、逻辑不通过（如余额不足）
401	Unauthorized	未提供 Token 或 Token 已过期
403	Forbidden	签名验证失败、权限不足
404	Not Found	资源不存在
429	Too Many Requests	触发限流
500	Internal Error	服务器内部故障

---

业务错误码 (Error Codes)

认证相关

错误码	说明
INVALID_SIGNATURE	EIP-712 签名验证失败
TIMESTAMP_EXPIRED	签名时间戳过期 (5分钟内有效)
UNAUTHORIZED	JWT Token 无效或已过期
INVALID_ADDRESS	无效的钱包地址格式

交易相关

错误码	说明
INSUFFICIENT_BALANCE	账户余额不足
INVALID_AMOUNT	无效的金额参数
INVALID_SYMBOL	不支持的交易对
INVALID_LEVERAGE	杠杆倍数超出范围 (1-50)
PRICE_REQUIRED	限价单需要指定价格
ORDER_NOT_FOUND	订单不存在或已被取消
ORDER_NOT_OWNED	无权操作此订单
ORDER_NOT_CANCELLABLE	订单无法取消
POSITION_NOT_FOUND	持仓不存在
MAX_LEVERAGE_EXCEEDED	超过了交易对允许的最大杠杆
MARGIN_TOO_LOW	剩余保证金不足以维持仓位
MATCHING_ERROR	撮合引擎错误

充提相关

错误码	说明
WITHDRAWAL_NOT_FOUND	提现记录不存在
INVALID_STATUS	状态不正确，只能取消 signed 状态的提现
CHAIN_ERROR	链上调用失败

推荐系统相关

错误码	说明
CODE_EXISTS	推荐码已存在
ALREADY_BOUND	用户已绑定推荐码
INVALID_CODE	无效的推荐码

通用错误

错误码	说明
REQUEST_FAILED	通用的请求执行失败
MARKET_NOT_FOUND	交易对不存在
RATE_LIMIT_EXCEEDED	请求频率超限

---

错误处理示例

TypeScript

interface APIError {
  error: string;
  message: string;
  code: number;
}

async function fetchWithErrorHandling<T>(url: string, options?: RequestInit): Promise<T> {
  const response = await fetch(url, options);

  if (!response.ok) {
    const error: APIError = await response.json();

    switch (error.error) {
      case 'UNAUTHORIZED':
        // Token 过期，重新登录
        await refreshToken();
        return fetchWithErrorHandling(url, options);

      case 'INSUFFICIENT_BALANCE':
        throw new Error(`余额不足: ${error.message}`);

      case 'TIMESTAMP_EXPIRED':
        throw new Error('签名已过期，请重新签名');

      default:
        throw new Error(error.message || '请求失败');
    }
  }

  return response.json();
}

React Hook

import { useState, useCallback } from 'react';

export function useAPIError() {
  const [error, setError] = useState<string | null>(null);

  const handleError = useCallback((err: any) => {
    if (err.error) {
      switch (err.error) {
        case 'INSUFFICIENT_BALANCE':
          setError('余额不足，请先充值');
          break;
        case 'INVALID_SIGNATURE':
          setError('签名验证失败，请重试');
          break;
        case 'UNAUTHORIZED':
          setError('登录已过期，请重新登录');
          break;
        default:
          setError(err.message || '操作失败');
      }
    } else {
      setError(err.message || '未知错误');
    }
  }, []);

  const clearError = useCallback(() => setError(null), []);

  return { error, handleError, clearError };
}