NueForm

速率限制

了解 NueForm API 速率限制、如何通过响应头监控使用情况以及保持在配额范围内的最佳实践。

NueForm API 通过速率限制确保公平使用和平台稳定性。限制按用户账户级别应用，使用 60 秒滑动窗口。

按计划的限制

计划每分钟请求数窗口
Pro10060 秒（滑动）
Enterprise50060 秒（滑动）

速率限制在账户级别应用，而不是按 API 密钥。如果您有多个密钥，它们共享相同的速率限制配额。

速率限制响应头

每个 API 响应都包含速率限制头，以便您实时监控使用情况：

头描述示例
X-RateLimit-Limit每个窗口允许的最大请求数100
X-RateLimit-Remaining当前窗口内剩余的请求数87
X-RateLimit-Reset窗口重置时的 ISO 8601 时间戳2026-02-28T14:30:45.000Z

响应头示例：

text
HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 2026-02-28T14:30:45.000Z

当您被限速时

如果超出速率限制，API 返回 429 Too Many Requests 响应。响应包含标准速率限制头以及 Retry-After 头，指示重试前需要等待的秒数。

响应

json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please try again later.",
    "status": 429
  }
}

429 响应的头

text
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-02-28T14:31:12.000Z
Retry-After: 27

Retry-After 值是当前窗口中最早请求过期并释放容量前需要等待的秒数。

监控使用情况

主动使用速率限制头以避免达到限制：

JavaScript

javascript
async function callApi(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  // 记录速率限制状态
  const remaining = response.headers.get("X-RateLimit-Remaining");
  const limit = response.headers.get("X-RateLimit-Limit");
  console.log(`Rate limit: ${remaining}/${limit} remaining`);

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get("Retry-After"), 10);
    console.warn(`Rate limited. Retrying in ${retryAfter} seconds...`);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    return callApi(url, options); // 重试
  }

  return response;
}

Python

python
import os
import time
import requests

API_KEY = os.environ["NUEFORM_API_KEY"]
BASE_URL = "https://app.nueform.com/api/v1"

def call_api(path, method="GET", **kwargs):
    url = f"{BASE_URL}{path}"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }

    response = requests.request(method, url, headers=headers, **kwargs)

    # 记录速率限制状态
    remaining = response.headers.get("X-RateLimit-Remaining")
    limit = response.headers.get("X-RateLimit-Limit")
    print(f"Rate limit: {remaining}/{limit} remaining")

    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 5))
        print(f"Rate limited. Retrying in {retry_after} seconds...")
        time.sleep(retry_after)
        return call_api(path, method, **kwargs)  # 重试

    return response

最佳实践

实施指数退避

收到 429 响应时，使用指数退避而不是立即重试。从 Retry-After 值开始，每次后续重试增加延迟。

javascript
async function fetchWithBackoff(url, options = {}, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, {
      ...options,
      headers: {
        "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
        "Content-Type": "application/json",
        ...options.headers,
      },
    });

    if (response.status !== 429) {
      return response;
    }

    if (attempt === maxRetries) {
      throw new Error("Max retries exceeded due to rate limiting");
    }

    const retryAfter = parseInt(
      response.headers.get("Retry-After") || "5",
      10
    );
    const backoff = retryAfter * Math.pow(2, attempt);
    console.warn(`Rate limited. Retry attempt ${attempt + 1} in ${backoff}s`);
    await new Promise((resolve) => setTimeout(resolve, backoff * 1000));
  }
}

缓存响应

通过本地缓存响应避免冗余 API 调用。表单定义和主题配置变化不频繁，是很好的缓存候选。

javascript
const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 分钟

async function getCachedForm(formId) {
  const cacheKey = `form_${formId}`;
  const cached = cache.get(cacheKey);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const response = await fetch(
    `https://app.nueform.com/api/v1/forms/${formId}`,
    {
      headers: {
        "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
      },
    }
  );

  const { data } = await response.json();
  cache.set(cacheKey, { data, timestamp: Date.now() });
  return data;
}

使用 Webhook 获取实时数据

不要轮询 API 获取新的表单响应，而是设置 Webhook 在提交到达时接收通知。这消除了重复的轮询请求并更快地传递数据。

尽可能批量操作

如果需要获取多个资源，使用带分页的列表端点而不是为每个资源单独发请求。单次调用

GET/api/v1/forms?per_page=100
比 100 次单独调用高效得多。

监控 X-RateLimit-Remaining 头

跟踪剩余配额并在达到限制前节流请求。如果 X-RateLimit-Remaining 降至 10 以下，考虑在请求之间添加短暂延迟。

速率限制保护平台上所有用户的利益。持续超出速率限制或试图绕过限制的应用程序可能会被暂停 API 访问。如果您需要更高的限制，请考虑升级到 Enterprise 计划或联系支持团队。

升级您的速率限制

如果您需要每分钟超过 100 个请求，升级到 Enterprise 计划可获得每分钟 500 个请求。如需超过 Enterprise 限制，请联系我们的销售团队讨论自定义方案。

计划速率限制价格
Pro100 请求/分钟$29/月
Enterprise500 请求/分钟$99/月
自定义可协商联系销售
最后更新：2026年4月6日