Limites de taxa | NueForm Docs

A API do NueForm aplica limites de taxa para garantir o uso justo e a estabilidade da plataforma. Os limites são aplicados por conta de usuário usando uma janela deslizante de 60 segundos.

Limites por plano

Plano	Requisições por minuto	Janela
Pro	100	60 segundos (deslizante)
Enterprise	500	60 segundos (deslizante)

Os limites de taxa são aplicados no nível da conta, não por chave de API. Se você tiver várias chaves, elas compartilham a mesma cota de limite de taxa.

Cabeçalhos de limite de taxa

Toda resposta da API inclui cabeçalhos de limite de taxa para que você possa monitorar seu uso em tempo real:

Cabeçalho	Descrição	Exemplo
`X-RateLimit-Limit`	Máximo de requisições permitidas por janela	`100`
`X-RateLimit-Remaining`	Requisições restantes na janela atual	`87`
`X-RateLimit-Reset`	Timestamp ISO 8601 de quando a janela é reiniciada	`2026-02-28T14:30:45.000Z`

Exemplo de cabeçalhos de resposta:

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

Quando você atinge o limite de taxa

Se você exceder seu limite de taxa, a API retorna uma resposta 429 Too Many Requests. A resposta inclui os cabeçalhos padrão de limite de taxa mais um cabeçalho Retry-After indicando quantos segundos aguardar antes de tentar novamente.

Resposta

json

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

Cabeçalhos em uma resposta 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

O valor de Retry-After é o número de segundos até que a requisição mais antiga na sua janela atual expire e haja capacidade disponível novamente.

Monitorando o uso

Use os cabeçalhos de limite de taxa de forma proativa para evitar atingir o limite:

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,
    },
  });

  // Log rate limit status
  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); // Retry
  }

  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)

    # Log rate limit status
    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)  # Retry

    return response

Boas práticas

Implemente backoff exponencial

Quando você receber uma resposta 429, use backoff exponencial em vez de tentar novamente imediatamente. Comece com o valor de Retry-After e aumente o atraso a cada nova tentativa.

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));
  }
}

Faça cache das respostas

Evite fazer chamadas redundantes à API armazenando respostas em cache localmente. Definições de formulários e configurações de tema mudam com pouca frequência e são boas candidatas para cache.

javascript

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

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;
}

Use webhooks para dados em tempo real

Em vez de consultar a API repetidamente em busca de novas respostas de formulários, configure webhooks para receber notificações quando os envios chegarem. Isso elimina requisições repetitivas de polling e entrega os dados mais rápido.

Agrupe operações quando possível

Se você precisar recuperar vários recursos, use endpoints de listagem com paginação em vez de fazer requisições individuais para cada recurso. Uma única chamada a

GET/api/v1/forms?per_page=100

é muito mais eficiente do que 100 chamadas separadas.

Monitore o cabeçalho `X-RateLimit-Remaining`

Acompanhe sua cota restante e reduza o ritmo das suas requisições antes de atingir o limite. Se X-RateLimit-Remaining cair abaixo de 10, considere adicionar um pequeno atraso entre as requisições.

Os limites de taxa protegem a plataforma para todos os usuários. Aplicações que excedem os limites de taxa de forma consistente ou tentam contorná-los podem ter o acesso à API suspenso. Se você precisar de limites maiores, considere fazer upgrade para o plano Enterprise ou entrar em contato com o suporte.

Fazendo upgrade do seu limite de taxa

Se você precisar de mais de 100 requisições por minuto, faça upgrade para o plano Enterprise e tenha 500 requisições por minuto. Para limites além do Enterprise, entre em contato com nosso time de vendas para discutir acordos personalizados.

Plano	Limite de taxa	Preço
Pro	100 req/min	US$ 29/mês
Enterprise	500 req/min	US$ 99/mês
Personalizado	Negociável	Fale com vendas