跳至正文
语言: zh
菜单

Fileverity API 文档

速率限制与 HTTP 头

每个 API 密钥的请求速率限制、速率限制响应头、429 和 503 响应中的 retry-after，以及 Fileverity API 设置的其他响应头。

查看 Markdown更新于 2026-11-04

每个 API 密钥每分钟最多可发起 120 次请求。该限制按一分钟的时间窗口计数，适用于所有接口，包括返回错误的请求。窗口用尽后，后续请求将收到 429，错误码为 rate_limited，直到窗口重置。

需要更高的限额或批量价格？联系销售团队。

速率限制响应头

对已通过身份验证的请求，每个响应都会携带您当前时间窗口的状态：

请求头含义
x-ratelimit-limit-requests每个窗口允许的请求数。
x-ratelimit-remaining-requests当前窗口剩余的请求数。
x-ratelimit-reset-requests距窗口重置的秒数。
retry-after仅在错误码为 rate_limited 的 429 响应和错误码为 service_unavailable 的 503 响应中出现。表示发起下一次请求前需等待的秒数。pending_files_limit（同为 429）不带此响应头。

因缺少密钥或密钥无效而被拒绝的请求（401）不带这些响应头。

async function call(url, init) {  for (let attempt = 0; attempt < 5; attempt++) {    const response = await fetch(url, init);    if (response.status !== 429) return response;    const wait = Number(response.headers.get("retry-after")) || 1;    await new Promise((resolve) => setTimeout(resolve, wait * 1000));  }  throw new Error("Rate limited");}

请将突发流量分散到不同时间；优先使用 Webhook 而非密集的轮询循环，并在分析中使用 Prefer: wait 代替轮询。资源繁忙时，POST /analyses 会返回 503 service_unavailable 及 retry-after；参见服务繁忙时。

其他响应头

请求头出现位置含义
x-request-id所有响应请求 ID，错误响应体中也包含该 ID。
cache-control: no-store所有响应API 响应不会被缓存。
preference-appliedPOST /analyses您的 Prefer 请求头生效时，值为 wait=N。
idempotent-replayedPOST 接口当响应是已保存响应的重放时为 true。参见幂等性。
x-evidence-includedGET /analyses/{id}/report.pdf文档证据已过期、PDF 中不再包含证据时为 false。

您发送的请求头

  • Authorization: Bearer <key>：必填。参见身份验证与密钥。
  • Content-Type: application/json 用于 JSON 请求体；multipart/form-data 用于 POST /files 上传。
  • Idempotency-Key：可选，用于 POST 请求。
  • Prefer: wait=N：可选，用于 POST /analyses。

示例：curl -i https://api.fileverity.com/v1/models -H "Authorization: Bearer $FILEVERITY_API_KEY" 会显示所有响应头。