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

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

这篇把欧易 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.InvalidNonce as e:
    print('时间戳过期(50102),先校准本机时间再重试:', e)
except ccxt.AuthenticationError as e:
    print('鉴权失败,先看报错里的 code 再决定查什么:', e)
except ccxt.RateLimitExceeded as e:
    print('触发限频,放慢请求:', e)
except ccxt.BaseError as e:
    print('其他报错,看原始 code/msg:', e)

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

高频报错对照表

下面这张表覆盖了新手容易撞上的几种报错。表里的错误码含义核于 2026-10,以欧易 API v5 文档 Error Code 一节为准(欧易偶尔会调整码值,遇到对不上的就以 msg 文字和官方文档为准),重点是把「原因→怎么修」对上号。鉴权这一类尤其要按 code 分支走:同样是「连不上」,50113 和 50105 要查的是完全不同的东西。

逐条排查怎么修

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

鉴权类(50101 / 50102 / 50105 / 50110 / 50111 / 50112 / 50113)与权限类(50120)

鉴权失败在 HTTP 层统统是 401,ccxt 里多数抛 AuthenticationError(50110 抛的 PermissionDenied 也是它的子类)。例外是 50102「时间戳过期」:按 ccxt 主分支 2026-09 的源码,它被映射成 InvalidNonce,归在 NetworkError 那一支,只写 except AuthenticationError 接不住它,得单独写一个分支。所以别照着「最常见的原因」挨个试——先把 code 抠出来,再按 code 走对应的那一条。50120「权限不足」要单独摘出来:它不在 401 那一堆里,按官方错误码表走的是 HTTP 200、靠 body 里的 code 判断,请求在协议层是「成功」的,只凭状态码你根本看不出它出了错。

• 50113 Invalid signature:查签名这一步。签名原文的拼接(请求方法、请求路径、请求体)、用来做 HMAC 的密钥是不是 secret、有没有按 HMAC-SHA256 算完再 Base64。用 ccxt 的话签名是库做的,这时先怀疑 secret 复制错了。
• 50105 Passphrase 不对(50104 是没填):只查口令。ccxt 里的 password 字段填的必须是你建 Key 时设的那串 Passphrase,不是登录密码,也不是 secret;记不清了只能删 Key 重建。
• 50102 / 50112 时间戳问题:只查时间。按官方文档,请求时间戳与服务器时间相差超过 30 秒就会被拒。开 NTP 自动校时,长期跑的机器定期确认它真的在同步。用 ccxt 的话,50102 抛的是 InvalidNonce,在它的分支里校完时间再重试;最后留一个 BaseError 兜底。
• 50111 Invalid OK-ACCESS-KEY:查 apiKey 本身——复制时首尾带了空格、漏了字符,或者 Key 已被删。
• 50101 APIKey 与当前环境不匹配:Key 本身没错,是环境对不上——模拟盘 Key 没开 set_sandbox_mode(True)(请求不带模拟盘标记头,按实盘处理),或实盘 Key 开了它。把 Key 和开关对齐,再打印 okx.headers.get('x-simulated-trading') 自检,模拟盘下应为 1。ccxt 里它抛的也是 AuthenticationError。
• 50110 IP 不在白名单:查网络出口,不是查凭证。见下面「IP 白名单」一节。
• 50120 权限不够(HTTP 200):凭证都对,只是这个 Key 没勾上对应权限。它不会以 401 的形式出现,只能读 body 里的 code——所以判断逻辑别只写 if status == 401。见下面「权限不足」。

顺带说一句:欧易的 msg 文字有时会直接点名是哪个 header 出的问题,把它和 code 一起原样记下来,比凭印象猜快得多。

权限不足

典型症状是「能查余额,不能下单」。查余额走读取权限,下单走交易权限,两者分开授权。回欧易后台 API 管理,找到这个 Key,补勾「交易」即可,不用重建。如果你顺手勾过提现——别留着,跑量化的 Key 永远别开提现权限。另外别把「交易权限」想得太窄:按欧易文档的定义,它除了下单撤单,还包含资金划转和一部分账户设置,所以为了做账户间划转去补勾提现是没必要的。

IP 白名单(50110)

这条报错说的是「你现在这个出口 IP 不在这把 Key 的名单里」,所以排查从网络出口开始,而不是从凭证开始:

• 先把当前出口 IP 查出来,和你在后台给这把 Key 填的名单逐个对一遍。注意是出口 IP:开了代理、走了公司网关、家里宽带重拨过,出口都可能和你以为的不是同一个。
• 出口 IP 不稳定,解决方向是把出口固定下来,而不是把锁拆掉:把策略挪到一台 IP 固定的机器上跑,或者在出口确实会变时有节奏地更新白名单。欧易这边每把 Key 最多绑 20 个 IP,支持 IPv4/IPv6 和网段,留出余量并不难。
• 调试阶段用只读 Key 或模拟盘 Key,别拿那把有交易权限的主力 Key 反复试。
• 不建议把「取消白名单」当常规排障动作。官方对绑 IP 的说法是强烈建议而非强制,但有一条规则要知道:没有绑定 IP、又带 trade 或 withdraw 权限的 Key,闲置 14 天后会被自动删除——所以不绑 IP 的 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: 里面紧接着打接口、中间不加任何延时。这种循环会在一秒内打出几十上百个请求,瞬间撞限频。任何高频循环里都要留间隔。

一个高频踩坑场景

常见问题

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