欧易 API 常见报错与排查清单:照着这张表修

写量化脚本的人,十有八九不是卡在策略上,而是卡在一行红字报错上:脚本跑起来,终端弹出一串看不懂的 code 和英文,人就懵了。好消息是,欧易 API 的报错就那么几种高频款,搞清楚每种长什么样、对应哪个原因,排查会快得多。

这篇我们(量化喵编辑组)把自己踩过、以及在社群里反复看到的报错整理成一份清单,核心是一张错误码对照表——出了问题,先到表里按错误码或关键词定位,再看下面对应的逐条排查。读完你应该能把大多数报错在几分钟内自己解决,而不是对着红字干瞪眼。

先学会读报错:code + msg

排错的第一步,是看懂报错本身。欧易接口出错时,会返回三样信息:

• HTTP 状态码:最粗的一层,比如 401(鉴权问题)、429(请求太多)、400(请求本身有问题)。
• code:欧易自己的数字错误码,最精确地指向问题类型。这是你排查的主要依据。
• msg:一段文字说明,帮你确认方向,有时还会直接点出哪个字段出错。

如果你用 ccxt,它会把这些原始报错包装成更易读的异常类型,比如鉴权问题抛 AuthenticationError、限频抛 RateLimitExceeded、余额不够抛 InsufficientFunds。异常信息里一般也带着欧易的原始 code 和 msg。一个好习惯是用 try/except 把它们打印清楚:

import ccxt

okx = ccxt.okx({
    'apiKey':   '你的_apiKey',
    'secret':   '你的_secret',
    'password': '你的_Passphrase',
    'enableRateLimit': True,
})

try:
    balance = okx.fetch_balance()
    print('USDT 可用:', balance['USDT']['free'])
except ccxt.AuthenticationError as e:
    print('鉴权失败,检查三个凭证和系统时间:', e)
except ccxt.RateLimitExceeded as e:
    print('触发限频,放慢请求:', e)
except ccxt.BaseError as e:
    print('其他报错,看原始 code/msg:', e)

把异常里那串 code 和 msg 原样记下来,对照下面这张表,基本就能定位到底是哪一类问题。

高频报错对照表

下面这张表覆盖了新手最常撞上的几种报错。错误码以欧易当前 API v5 文档公布的为准(欧易偶尔会调整码值,遇到对不上的就以 msg 文字和官方文档为准),重点是把「原因→怎么修」对上号。

逐条排查怎么修

表格给方向,这一节给细节。挑你撞上的那条往下看。

鉴权类(Invalid sign / API key 无效 / Passphrase 错误)

这是新手报错的重灾区,按下面顺序排查,命中率最高:

• 先查 Passphrase。ccxt 里的 password 字段,填的必须是你建 Key 时设的那串 Passphrase,不是登录密码,也不是 secret。这一条占了鉴权失败的一大半。
• 再查 apiKey / secret 有没有复制错。常见是粘贴时首尾多了空格、或漏了一两个字符。重新从后台复制一遍最稳妥。
• 还要查系统时间。时间不准会让签名时间戳过期,表现也是鉴权失败。开 NTP 校时。

权限不足

典型症状是「能查余额,不能下单」。查余额走读取权限,下单走交易权限,两者分开授权。回欧易后台 API 管理,找到这个 Key,补勾「交易」即可,不用重建。如果你顺手勾过提现——别留着,跑量化的 Key 永远别开提现权限。

余额不足

除了字面意义的钱不够,还有一个隐蔽原因:欧易有不同的账户(资金账户、交易账户等),你的钱可能不在用于下单的那个账户里。确认资金已经划转到交易账户。模拟盘的话,虚拟资金用完了在模拟盘界面重置即可——这也是 先在模拟盘练手 的好处,试错不花真钱。

symbol / 精度类

现货交易对在 ccxt 里统一是 大写/大写 带正斜杠,比如 BTC/USDT。写成 BTCUSDT、小写、或用合约格式都会报错。数量太小或精度不对,就用 load_markets() 查这个交易对的最小下单量和精度,按它要求来。这块在我们的 API 量化入门 里有完整的下单示例。

限频与退避重试

限频(50011 / Too Many Requests)是脚本党最常撞、也最该提前防的一类。它不是你做错了什么,而是请求太密集触发了交易所的保护。处理它分两层:

第一层:打开 ccxt 自带的限速。初始化时加 'enableRateLimit': True,ccxt 会自动在请求之间插入合理间隔,大多数场景这一步就够了:

okx = ccxt.okx({
    'apiKey':   '你的_apiKey',
    'secret':   '你的_secret',
    'password': '你的_Passphrase',
    'enableRateLimit': True,   # 自动限速,先开上
})

第二层:加指数退避重试。如果你的策略在某些时刻请求确实很密(比如同时刷很多交易对),光靠自动限速可能还会偶尔撞。这时给关键请求包一层重试:撞一次等 1 秒再试,再撞等 2 秒、4 秒,逐步拉长,撞够几次就放弃报错。

import ccxt, time

def with_retry(fn, max_tries=5):
    delay = 1
    for i in range(max_tries):
        try:
            return fn()
        except ccxt.RateLimitExceeded:
            print(f'限频,第 {i+1} 次,等 {delay}s 再试')
            time.sleep(delay)
            delay *= 2          # 指数退避:1 → 2 → 4 → 8 ...
    raise RuntimeError('重试多次仍被限频,放弃')

# 用法:把会被限频的调用丢进去
ticker = with_retry(lambda: okx.fetch_ticker('BTC/USDT'))
print(ticker['last'])

一个反面教材:别写 while True: 里面紧接着打接口、中间不加任何延时。这种循环会在一秒内打出几十上百个请求,瞬间撞限频,严重时整个 Key 会被短暂限制。任何高频循环里都要留间隔。

实测:我们踩的一次坑

常见问题

把报错排查这关过了,你的脚本就不会动不动卡死了。接下来值得花时间的是把 风控写进代码——比报错更可怕的是脚本没报错却一直在下错单。也别忘了新代码先丢 模拟盘 里跑,排错不花真钱。