币安 API 返回 -2015 —— 从 Key 本身查到 IP 白名单和接口权限
-2015 只回一句笼统的英文,卡在哪里得自己一层层排除;本页给出每一层该打印什么、对照什么。
下单或查账户时返回 -2015,消息是 Invalid API-key, IP, or permissions for action.。这一句把几种情况捆在一起报,返回里看不出是哪一种,只能按 Key、IP 白名单、接口权限的顺序一项项排除。币安开发者文档的现货错误代码中文页这样解释:
-2015 API Key权限，例如该Key不存在、请求并非来自允许的IP范围、或者该接口对应权限未开放
Invalid API-key, IP, or permissions for action.这三种只是举例,排查先从这三项入手。U 本位合约那边同一条叫 REJECTED_MBX_KEY,消息原文一字不差,所以现货脚本和合约脚本按同一套顺序查。
动手之前准备两样东西:脚本这次实际发出去的请求(地址、请求头、参数),以及这把 Key 在币安 API 管理页里的设置。脚本要是由 AI 写的,读 Key、算签名、发请求可能分散在好几个函数里;排查时直接在发请求前一行把这些值打印出来对照,比回头读代码快。
1. -2015 和 -2014、-1022、-1002 怎么区分 #
几条相邻的错误码都和 Key 或权限有关,先看清返回的到底是哪一个:
| 错误码(U 本位名称) | 消息原文 | 现货中文说明 | 先查哪里 |
|---|---|---|---|
| -2014 BAD_API_KEY_FMT | API-key format invalid. | API Key 格式无效 | 请求头里那串 Key 的字符本身 |
| -2015 REJECTED_MBX_KEY | Invalid API-key, IP, or permissions for action. | Key 不存在、IP 不在允许范围、接口权限未开放等 | 本文第 2–4 节 |
| -1022 INVALID_SIGNATURE | Signature for this request is not valid. | 签名不正确,通常是因为客户端代码中使用的 apisecret 错误 | 算签名用的 Secret |
| -1002 UNAUTHORIZED | You are not authorized to execute this request. | 未授权,请检查你的(API)权限 | 这把 Key 开了哪些权限 |
返回的如果是 -1021,问题出在时间戳,和 Key 无关,按币安 API 报 -1021 怎么办:时间戳超出 recvWindow 的排查顺序去查。
2. 核对请求头里带的是不是你以为的那把 Key #
请求示例里,Key 放在请求头 X-MBX-APIKEY 中。系统生成的 Key 用 HMAC 算法,创建时会给你两串:API 密钥和加密密钥。请求头里放 API 密钥,加密密钥只用来算签名,别放反。自行生成的 Ed25519 或 RSA Key 走另一条路:公私钥对由你自己用第三方软件生成,只把公钥交给币安。
按下面几项对照:
- 在发请求前打印出实际发出去的那串 Key 的长度和首尾几位,和你保存的那把逐字比,看有没有多出空格、换行,或者少了字符。
- 到 API 管理页确认这把 Key 还在。账户出现异常活动时,应立即撤销所有 Key 并联系币安客服;撤销过 Key 的,脚本配置要换成新建的那一把。
- 确认 Key 和接口地址出自同一个环境。现货测试网的 Key 要在测试网网站上单独生成,和主站账户的 Key 不通用。脚本拿测试网的 Key 去请求
api.binance.com,或者反过来,服务器那边找不到这把 Key,撞上的很可能就是 -2015 里「该 Key 不存在」那一种。
测试网地址和主站地址的对照表,见AI 写的币安交易脚本先跑现货测试网:怎么接、和实盘差在哪。
3. IP 白名单要填脚本出口的 IPv4 地址 #
中文说明列的第二种情况是请求并非来自允许的 IP 范围。给 Key 设了 IP 访问限制,请求就得从名单里的地址发出;脚本换了机器、换了网络,出口地址不在名单上,就会被拒。
不设白名单也有代价:无 IP 访问限制的 HMAC API 密钥除读取权限之外没有任何权限。想开其他权限,要添加 IP 访问(IPv4 格式)限制、使用自行生成的密钥(如 Ed25519 或 RSA),或者禁用默认安全控制措施。提现权限没有替代办法,必须添加 IPv4 格式的 IP 访问限制(币安帮助中心《如何在币安创建API密钥》)。
白名单只收 IPv4 格式,填哪一个地址要自己核:
- 在跑脚本的那台机器上查它访问外网时的出口 IPv4 地址,别在自己的电脑上查。脚本放在云服务器上,就去云服务器上查。
- 家用宽带、手机热点的出口地址可能会变。上周还能跑、今天突然报 -2015 的,先比对当前出口地址和白名单里的地址。
4. 现货下单、合约、提现要各自在 API 管理里开权限 #
每个接口名旁边都标着安全类型,比如下单接口标的是 New order (TRADE)。没标的算 NONE,其余带安全类型的都是要签名的 SIGNED 请求。一把 Key 可以只开放某几类接口的访问。默认情况下 API Key 不能交易,要先在 API 管理里开启交易。
| 要调的接口 | 安全类型 / 权限 | 开得出来的前提 |
|---|---|---|
| 公开行情 | NONE | 不需要签名 |
| 订单状态、成交历史等账户信息 | USER_DATA | 文档举例:可以单独用一把只带 USER_DATA 权限的 Key 盯订单状态 |
| 现货下单、撤单 | TRADE,需在 API 管理里开启交易 | 系统生成的 HMAC Key 要先满足第 3 节那几种条件之一 |
| 合约下单 | 合约交易权限 | Key 在启用合约账户之前创建,或已开通统一账户,这把 Key 都无法启用合约交易权限 |
| 提现 | 提现权限 | 必须添加 IPv4 格式的 IP 访问限制 |
合约那一行容易漏看。排查时看一眼这把 Key 的创建时间,早于还是晚于你开通合约账户,再看账户有没有开通统一账户。另有一条地区条件:自 2023 年 1 月 30 日 00:00(UTC)起,只有 IP 地址在非受限地区时,才能把系统生成的 API 密钥权限设置为【允许读取】。
让 AI 写脚本时,要它把每一个调用的接口和它的安全类型列成一张表,再拿这张表去对 API 管理里实际勾选的权限。只给 AI 读数据、不让它下单的,开哪一档就够,见给 AI 开 Binance API：只开只读权限，提现权限绝不能开。
5. 这把 Key 怎么建的,决定了它能调哪些接口 #
币安 API 不设 IP 白名单能下单吗?
系统生成的 HMAC Key 不行,不加 IP 访问限制时它只有读取权限。要开交易权限,可以添加 IPv4 格式的白名单,或者改用自行生成的密钥(如 Ed25519、RSA),或者禁用默认安全控制措施。
币安 API 报 -1022 签名错误要查哪里?
-1022 指请求里带的 signature 和服务器按规则算出来的不一致,通常是因为客户端代码中使用的 apisecret 错误(币安现货错误代码说明)。先核对算签名用的是不是和这把 API Key 配对的那串加密密钥,再看签名前拼出来的参数串和实际发出去的是否一致。
币安 API Key 怎么开合约交易权限?
要在 API 管理里给这把 Key 启用合约交易权限,前提是 Key 在启用合约账户之后创建,并且账户没有开通统一账户。Key 建得比合约账户早,或者已经开通统一账户,这一项就开不出来。
— PromptDeck, 2026-10-24