速率限制、错误与计费
速率限制
限制按密钥、按访问模式计算：
| 访问模式 | 限制 |
|---|---|
free（元数据：health、me、discover） | 60 次请求/小时，突发上限 1 次/秒 |
| basic（付费，上线后） | 1,000 次请求/小时 |
| premium（付费，上线后） | 5,000 次请求/小时 |
| pro（付费，上线后） | 15,000 次请求/小时 |
| partner / enterprise | 由管理员配置 |
任何 cogv_test_ 沙盒密钥 | 25 次请求/小时且 100 次/天 |
新密钥初始仅有 free 元数据访问。试用（trial）访问由管理员授予，额度有限且会过期；partner 和 enterprise 的限制按协议配置，请通过 dApp 申请访问。API 会返回标准的 RateLimit-* 响应头；用尽额度后会收到 429 rate_limited。
错误码
| 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 | insufficient_credits | 付费使用：你的 Cognivo 积分余额不足以覆盖本次调用（未产生任何扣费） |
| 402 | payment_required | 该端点在此密钥上需要付费访问，且没有有效的支付路径覆盖本次调用（未产生任何扣费） |
| 403 | access_required | 该密钥没有实时情报端点的访问授权 - 请申请 trial、partner、付费或 enterprise 访问 |
| 403 | sandbox_limited | 沙盒（cogv_test_）密钥在其管理员启用的演示额度之外尝试了实时调用 |
| 403 | trial_expired | 该密钥的试用访问已过期 |
| 403 | trial_exhausted | 该密钥的试用额度已用完 |
| 403 | endpoint_denied | 该密钥的访问授权不覆盖这个特定端点 |
| 403 | suspended_key | 该密钥已被管理员暂停 |
| 403 | revoked_api_key | 密钥已被吊销或已被轮换替代 |
| 403 | project_disabled | 所属项目已被暂停或归档 |
| 403 | scope_denied | 密钥缺少该端点所需的权限范围 |
| 403 | origin_denied | 密钥配置了 Origin/IP 白名单且未匹配 |
| 404 | public_api_disabled | 公开 API 已被临时关闭 |
| 422 | insufficient_data（及类似代码） | 工具已运行但无法为公允结果找到依据 - 不会向你收费 |
| 429 | rate_limited | 每小时额度已用尽 |
| 500 | internal_error | 意外故障 - 联系支持时请附上 request_id |
| 503 | billing_unavailable / 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_开头；检查是否完整复制了密钥且前后没有空白字符。如果原始密钥已丢失，请在门户中轮换密钥并使用新的。 - 403
revoked_api_key- 此密钥已被吊销或已被轮换替代。请从门户获取最新的密钥；旧密钥永远不会再生效。 - 403
scope_denied- 密钥有效，但缺少该端点所需的权限范围（例如wallet/approvals需要security:read）。编辑密钥的权限范围，或创建一个具有正确权限范围的密钥；参见认证与 API 密钥。 - 403
origin_denied- 密钥配置了 Origin 或 IP 白名单，而本次请求来自其他地方。请从白名单内的来源/IP 发起调用，或清空密钥上的白名单。 - 403
access_required- 密钥有效，但没有实时情报端点的访问授权。请在开发者门户申请 trial、partner、付费或 enterprise 访问；没有授权时调用绝不会执行（也绝不会扣费）。 - 403
sandbox_limited- 沙盒（cogv_test_）密钥在其演示额度之外尝试了实时情报调用。请让管理员为该密钥启用实时演示额度，或改用具有访问授权的正式密钥。 - 403
trial_expired/trial_exhausted- 你的试用已结束（时间到期或额度用完）。请申请延期，或转为付费、partner 或 enterprise 访问。 - 403
endpoint_denied- 你的访问授权覆盖其他端点，但不覆盖这一个（端点级访问在 partner/enterprise 授权中很常见）。请申请该端点的访问权限。 - 403
suspended_key- 该密钥已被管理员暂停。请通过 dApp 联系支持并附上你的request_id。 - 402
payment_required- 本次调用在此密钥上需要付费访问。请充值 Cognivo 积分，或申请覆盖该端点的访问模式；未产生任何扣费。 - 429
rate_limited- 你用完了此密钥的额度。降低频率、在客户端加入带退避的排队机制，或申请更高的访问模式。记住cogv_test_沙盒密钥的上限是 25 次请求/小时且 100 次/天；free 元数据访问的上限是 60 次/小时，突发上限 1 次/秒。 - 400
invalid_chain-chain必须是eth、base或bsc。像ethereum这样的名称或8453这样的数字链 ID 都不被接受。 - 400
invalid_address/invalid_wallet/invalid_token- 请发送完整的0x+ 40 个十六进制字符的地址。API 不解析 ENS 名称和代币符号。 - 422
insufficient_data- 不是故障，也不是你的错：工具已运行，但无法为公允答案找到依据（例如对一个在该代币上没有可定价交易的钱包调用wallet/pnl）。422 永远不会向你收费；换一个钱包/代币或换个更宽泛的问题试试。 - 404
public_api_disabled- 公开 API 被临时关闭了，不是 URL 写错。请稍后重试，或查看公告频道。
访问、计费与积分
Developer API 在早期访问期间实行访问控制。免费密钥可以探索：阅读文档、调用 GET /v1/api/health、通过 GET /v1/api/me 自查密钥，以及进行有限的沙盒/演示调用。实时情报端点需要 trial、partner、付费或 enterprise 访问；没有访问授权时，它们会返回明确的错误（access_required、trial_expired、payment_required 等），而不是免费运行。
- 付费使用按每次成功调用以 Cognivo 积分计费，从你已有的 Cognivo 积分余额（与 Chat/Telegram 相同的积分）中扣除，由项目所有者的账户支出。失败、超时、空结果和错误不收费。
- 扣费是幂等的 - 重试或重复的请求不会导致重复扣费。
- 沙盒（
cogv_test_）密钥用于集成测试：上限为 25 次请求/小时且 100 次/天，并且只有在管理员启用后才能运行少量实时演示额度。 - 试用（trial）访问由管理员授予，额度有限且会过期。
- Enterprise 为定制方案：定价、更高的限制和端点级访问 - 请通过 dApp 申请访问。
各端点的积分费用（适用于付费使用；为透明起见公示）：
| 端点 | 每次成功调用的积分 |
|---|---|
intel/liquidity | 2 |
intel/risk | 2 |
wallet/approvals | 2 |
intel/why-down | 3 |
intel/team-wallets | 5 |
wallet/exact-movements | 5 |
wallet/pnl | 10 |
health、me | 免费 |
discover | 免费，但速率上限很严格 |
不是投资建议
API 结果是链上情报信号，不是投资建议；没有发现红旗信号也不能证明安全。请务必自己做研究。