速率限制

了解FreeFileTools API的速率限制以及如何在应用程序中处理它们。

免费套餐限制

限制	值
每小时请求数	`50`
每次请求的最大文件大小	`25 MB`
速率限制窗口	`Rolling 1 hour`

速率限制按API Key应用。每个密钥有独立的计数器，在滚动的一小时周期内重置。

超出速率限制时

超出速率限制时，API返回429 Too Many Requests响应：

json

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 50 requests per hour. Please try again later.",
  "retryAfter": 1742
}

retryAfter字段指示在发送下一个请求之前需要等待的秒数。

速率限制响应头

每个API响应都包含帮助您跟踪速率限制使用情况的头：

头	描述
`X-RateLimit-Limit`	每小时允许的最大请求数（50）
`X-RateLimit-Remaining`	当前窗口中剩余的请求数
`Retry-After`	重试前等待的秒数（仅在429响应时）

响应头示例

http

HTTP/1.1 200 OK
Content-Type: image/jpeg
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 42

保持在限制范围内的技巧

检查剩余请求数

监控X-RateLimit-Remaining头以了解剩余请求数量。

实现指数退避

收到429响应时，使用递增的延迟进行等待和重试，而不是频繁请求API。

缓存结果

如果重复处理相同的文件，请在本地缓存结果以避免不必要的API调用。

合理批量处理

进行批量处理时，将请求分散在时间上，而不是一次性全部发送。

示例：在JavaScript中处理速率限制

javascript

async function apiCall(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get("Retry-After") || "60");
      console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }

  throw new Error("Max retries exceeded");
}