API

错误和限额

每种错误的含义、哪些应当重试、一个密钥能调用多少次，以及可以同时运行多少个请求。

错误格式

错误会返回状态码和 JSON 响应体：一条可展示的消息，以及一个可据以处理的错误码。

response.json (402)

1{2  "error": "No analyses left this month. Add a credit pack or move to a bigger plan.",3  "code": "no_credits"4}

错误码

状态码	错误码	含义	是否重试
400	—	请求有误：地址无效、深度超出范围、缺少字段。	否，先修正
401	`login`	没有发送密钥。	否
401	`invalid_key`	密钥无效或已被撤销。	否
402	`no_credits`	套餐和积分包都已用完。	充值后
402	`payment_required`	向付费接口发送请求时没有带密钥：按次付费（见x402），或发送密钥。	附上付款后
429	`quota_exceeded`	超出密钥的调用限额：免费版每天 10 次，或你套餐的每 10 分钟调用数。	在 `Retry-After` 之后
429	`daily_limit`	免费版某项免费工具当天已用完：20 次发射工具扫描、20 次交易摘要或 50 次多链检查。	UTC 00:00 之后
429	`rate_limited`	你的账户同时运行的请求过多。	是，等其中一个完成后
500	—	分析或追踪失败。	是
503	`busy`	Iris 已满负荷。	是，几秒后
503	`unavailable`	请求所需的某项功能在此服务器上已关闭，例如 EVM 分析。	稍后
504	`timeout`	处理时间过长。	是，可尝试降低深度

退款

失败的请求不计费：错误、超时，以及只能返回标签的分析（meta.scope database）。x-iris-credits 响应头始终显示调用后的余额。

限额

使用密钥对 API 和 MCP 的调用按密钥所属账户计数。网站本身从不受此限制，通过x402 按次付费的调用也不计入。

套餐	调用次数
免费版	每天（UTC）10 次
Individual	每 10 分钟 50 次
Sleuth	每 10 分钟 150 次
Investigator	每 10 分钟 250 次
Pro	每 10 分钟 500 次
API Starter	每 10 分钟 120 次
API Growth	每 10 分钟 500 次
API Scale	每 10 分钟 2,500 次

每个使用密钥的调用都带有以下响应头。超出限额后，调用会在执行任何工作之前停止，且不扣费：返回 429，错误码为 quota_exceeded，并附有 Retry-After。通过 MCP 调用时，工具会返回带有相同错误码的错误。

响应头	含义
`X-RateLimit-Limit`	当前窗口内允许的调用次数。
`X-RateLimit-Remaining`	当前窗口内剩余的调用次数。
`X-RateLimit-Reset`	窗口重置的时间，Unix 秒。

response.json (429)

1{2  "error": "This account made its 50 API calls for these 10 minutes: try again in 240 seconds, or move to a bigger plan: https://iriscan.app/pricing.",3  "code": "quota_exceeded",4  "limit": 50,5  "window_seconds": 600,6  "reset_at": "2026-10-16T14:30:00Z"7}

窗口是固定的：一天从 UTC 00:00 开始，10 分钟窗口从 :00、:10、:20 等开始。失败的调用会归还名额。有套餐时，在网站上打开的交易摘要也计入同一上限。没有套餐时，免费工具也有上限：每天 20 次发射工具扫描、20 次交易摘要和 50 次多链检查，之后返回 429，错误码为 daily_limit，直到 UTC 00:00。

每个账户同时最多 3 个请求（分析、追踪、内部钱包搜索、资金追踪和受害者扫描合计）。第四个会收到 429。
Iris 满负荷时，请求最多等待 20 秒排队，然后收到 503。
超过 2 分钟的任务会以 504 停止。

正确地重试

对 429 的 quota_exceeded 或 daily_limit，在其 Retry-After 之后重试。其他 429、500、503 和 504 以递增的延迟重试（2 秒、4 秒、8 秒…）。绝不要原样重试 400、401 或 402。