速率限制、错误与账单
本页是三件会让集成停摆的事情的参考：请求次数用完、收到错误返回，以及积分用光。它还会告诉你在账户里从哪里盯住这三件事。
当一个昨天还能用的调用返回了你不认识的代码时，当你在估算自己的应用能发多少请求时，或者当你想在上线前准确知道一次调用要花多少钱时，就来看这一页。
速率限制
限额按密钥设定，取决于访问模式：
| 访问模式 | 限额 |
|---|---|
| 正式付费：basic（每个新正式密钥的默认值） | 1,000 次请求/小时 |
| 正式付费：premium（由管理员分配） | 5,000 次请求/小时 |
| 正式付费：pro（由管理员分配） | 15,000 次请求/小时 |
| 合作伙伴或企业级 | 由管理员配置 |
任何 cogv_test_ 沙盒密钥 | 25 次请求/小时，100 次/天，1 次/秒 |
元数据接口（health、me、discover），使用任何有效密钥 | 60 次请求/小时，1 次/秒 |
新的正式密钥从 basic 起步，没有审批步骤。premium 和 pro 由 Cognivo 分配，合作伙伴和企业级的限额按协议设定。每一次调用都会返回标准的 RateLimit-* 响应头，所以你不用靠猜就能看到剩余额度。额度用完时你会收到 429 rate_limited，并附带一个 Retry-After 响应头，告诉你何时再试。
关注你的用量
登录 dApp，在左侧边栏打开 账户，选择 Developers，然后打开 Usage 标签页。
顶部的时间窗选择器可在 最近 24 小时、最近 7 天 和 最近 30 天 之间切换。旁边有一个标签显示你的积分余额，另一个显示适用于你的密钥的速率层级和每小时限额。再往下，五个计数器把这个时间窗拆成请求数、成功数、错误数、被限速数和已用积分，而 结果分布 卡片把同一个时间窗从三个角度拆开。
报价与实扣 是你在担心账单之前该读的那个面板。用产品自己的话说："报价是标价。实扣是真正从你余额里出去的钱。"这两个数字并不总是一样，因为失败的调用、被拒绝的调用和诚实为空的答案都会被报价，但从不扣费。
请求历史 列出单次调用，可以按密钥、端点和状态筛选。两种空状态含义不同。"没有请求符合这些筛选条件。"表示这个时间窗内存在调用，但没有一个符合你的筛选，所以请放宽筛选条件。"这个时间窗内还没有用量。"表示你的任何密钥在这个时间窗内都没有产生过调用。两者都不是错误，也都不代表某次调用丢失了。如果你预期有流量却看到零，请确认你的应用用的确实是你以为的那个密钥，并把时间窗放宽。
错误代码
| HTTP | error | 含义 |
|---|---|---|
| 400 | bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token | 输入格式有误。chain 必须是 eth、base 或 bsc，地址必须是 0x 加 40 个十六进制字符。 |
| 401 | missing_api_key | 没有提供 X-API-Key 或 Bearer 令牌。 |
| 401 | invalid_api_key | 密钥未知，或者不是 Cognivo v2 密钥。 |
| 402 | payment_required | Cognivo 积分不足以支付这次调用。没有扣费。 |
| 403 | access_required | 一个仅限元数据的旧密钥尝试了正式调用。 |
| 403 | sandbox_limited | 一个沙盒（cogv_test_）密钥尝试了正式情报调用。 |
| 403 | trial_expired | 该密钥的可选试用额度已过期。 |
| 403 | trial_exhausted | 该密钥的可选试用额度已用尽。 |
| 403 | endpoint_denied | 该密钥的访问安排不包含这个端点。 |
| 403 | chain_denied | 该密钥被限制在特定网络上，而这次请求指名了另一个网络。在任何上游调用之前、任何额度被消耗之前就被拒绝。 |
| 403 | key_expired | 该密钥已过期。它在所有地方都被拒绝，包括 GET /v1/api/me。 |
| 403 | suspended_key | 该密钥已被暂停，无法执行。门户会显示原因。 |
| 403 | revoked_api_key | 该密钥已被吊销或已被轮换替换。 |
| 403 | project_disabled | 所属项目已被暂停或归档。 |
| 403 | scope_denied | 该密钥缺少这个端点所需的权限范围。 |
| 403 | origin_denied | 该密钥上配置了来源或 IP 允许列表，而这次请求不匹配。 |
| 404 | public_api_disabled | 公开 API 已被临时关闭。 |
| 422 | insufficient_data 及类似代码 | 工具运行了，但无法给出有据可依的公允结果。你不会被扣费。 |
| 429 | rate_limited | 速率额度已耗尽。响应中带有 Retry-After。 |
| 500 | internal_error | 意外故障。联系支持时请附上 request_id。 |
| 503 | pricing_mismatch / billing_unavailable / billing_commit_failed / unavailable | 罕见的计费或依赖故障。没有扣费，重试即可。 |
每个响应都带有 request_id，成功的响应会在 meta.request_id 中再给出一次。请保留它。支持团队可以凭这一个值追溯单次调用。
常见错误及其修复方法
- 401
missing_api_key。 密钥根本没有到达我们这里。请在X-API-Key请求头中原样发送它，或者用Authorization: Bearer YOUR_API_KEY，并检查是否有代理把这个请求头剥掉了。 - 401
invalid_api_key。 密钥必须以cogv_live_或cogv_test_开头。请完整复制密钥，不要带前后空白。如果原始密钥丢了，请在门户中轮换密钥并使用新的。 - 402
payment_required。 在你的 Cognivo 账单页面充值后重试。没有扣费。GET /v1/api/me会显示你当前的余额。 - 403
revoked_api_key。 从门户中取用最新的密钥。旧的那个永远不会再生效。 - 403
scope_denied。 密钥本身有效，但缺少这个端点所需的权限范围，例如wallet/approvals需要security:read。参见 认证与 API 密钥。 - 403
origin_denied。 请从允许列表中的来源或 IP 发起调用，或者清空密钥上的这些列表。 - 403
access_required。 这是自助计费之前的、仅限元数据的旧密钥。请在门户中创建一个新的正式密钥。 - 403
sandbox_limited。 沙盒密钥用于测试，无法运行正式情报调用。请创建一个正式密钥。 - 403
chain_denied。 请在GET /v1/api/me中查看allowed_chains。那里的null表示没有限制。没有扣费。 - 403
trial_expired或trial_exhausted。 可选的评估额度已结束。你并不需要试用，改用普通的正式密钥即可。 - 403
endpoint_denied。 你的安排覆盖了其他端点，但不包含这一个。请申请把它加进来。 - 403
suspended_key。 门户会显示原因。如果不清楚，请从 dApp 联系支持并附上你的request_id。 - 429
rate_limited。 请遵守Retry-After响应头，并在客户端加入带退避的排队，或者申请更高的限额。 - 400
invalid_chain。 请使用eth、base或bsc。像ethereum这样的名称和数字形式的链 id 都不被接受。 - 400
invalid_address、invalid_wallet、invalid_token。 请发送完整的0x加 40 个十六进制字符的地址。API 不解析 ENS 名称或代币符号。 - 422
insufficient_data。 这不是故障，也不是你的错。工具运行了，但无法给出有据可依的公允答案，例如对一个在该代币上没有可定价交易的钱包调用wallet/pnl。它表示 Cognivo 无法核实这个答案，而不是说答案为零。422 永远不会向你收费。 - 404
public_api_disabled。 公开 API 已被临时关闭。这不是 URL 写错了，稍后再试即可。
积分与账单
正式密钥是自助开通的。没有申请，也没有订阅。新的正式密钥立即可用，每一次成功的调用都会从项目所有者的 Cognivo 积分余额中扣掉该端点的积分价格，用的就是 Chat 和 dApp 使用的同一份积分。每个账户每天获得 5 个免费积分，它们在 UTC 午夜重置。目前 Developer API 调用的计费处于关闭状态，因此成功调用不会扣除任何积分，你的余额也不会变化。
每个端点的积分价格都印在 Developers 页面 端点 标签页里它的旁边，免费端点在那里标为 Free。请从门户读取价格，而不要把它写死在代码里。
- 失败的调用从不收费。 错误、超时、被拒绝的调用和限速都不花钱。
- 成功的调用恰好只扣一次费，所以重试是安全的。
- 诚实为空的结果是免费的。 一个 422，以及一个空的
wallet/approvals列表，都是有效答案，不会被扣费。 - 积分不足 会给你
402 payment_required，且不扣费。请在 dApp 中充值后重试。 - 沙盒（
cogv_test_）密钥 从不收费，也无法运行正式情报调用。 - 被暂停的密钥和被停用的项目 无法执行任何操作，也从不收费。
- 企业级 是用于定制定价、定制限额和大用量的申请路径，你可以从 dApp 提交申请。
诚实地解读结果
API 结果描述的是 Cognivo 检查了什么以及在链上发现了什么。干净的结果不能证明某个代币或钱包是安全的，被标记的结果也不能证明存在欺诈。缺失或不可用的字段表示 Cognivo 无法核实那一项，而不是说那里什么都没有。请把每一个响应都当作你自己研究的一项输入。
下一步
在 端点参考 中查阅参数、权限范围和示例响应，用 认证与 API 密钥 收紧你的密钥，或者在 账单与积分包 中了解积分在产品其余部分是如何运作的。