Límites de velocidad | NueForm Docs

La API de NueForm aplica límites de velocidad para garantizar un uso justo y la estabilidad de la plataforma. Los límites se aplican por cuenta de usuario usando una ventana deslizante de 60 segundos.

Límites por plan

Plan	Solicitudes por minuto	Ventana
Pro	100	60 segundos (deslizante)
Enterprise	500	60 segundos (deslizante)

Los límites de velocidad se aplican a nivel de cuenta, no por clave de API. Si tienes múltiples claves, comparten la misma cuota de límite de velocidad.

Encabezados de límite de velocidad

Cada respuesta de la API incluye encabezados de límite de velocidad para que puedas monitorear tu uso en tiempo real:

Encabezado	Descripción	Ejemplo
`X-RateLimit-Limit`	Máximo de solicitudes permitidas por ventana	`100`
`X-RateLimit-Remaining`	Solicitudes restantes en la ventana actual	`87`
`X-RateLimit-Reset`	Marca de tiempo ISO 8601 cuando la ventana se reinicia	`2026-02-28T14:30:45.000Z`

Ejemplo de encabezados de respuesta:

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

Cuando se excede el límite de velocidad

Si excedes tu límite de velocidad, la API devuelve una respuesta 429 Too Many Requests. La respuesta incluye los encabezados estándar de límite de velocidad más un encabezado Retry-After que indica cuántos segundos esperar antes de reintentar.

Respuesta

json

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

Encabezados en una respuesta 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

El valor de Retry-After es el número de segundos hasta que la solicitud más antigua en tu ventana actual expire y se libere capacidad.

Monitoreo de uso

Usa los encabezados de límite de velocidad de forma proactiva para evitar alcanzar el límite:

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

  // Registrar estado del límite de velocidad
  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); // Reintentar
  }

  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)

    # Registrar estado del límite de velocidad
    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)  # Reintentar

    return response

Mejores prácticas

Implementa retroceso exponencial

Cuando recibas una respuesta 429, usa retroceso exponencial en lugar de reintentar inmediatamente. Comienza con el valor de Retry-After y aumenta el retraso con cada reintento subsiguiente.

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

Almacena respuestas en caché

Evita hacer llamadas redundantes a la API almacenando respuestas en caché localmente. Las definiciones de formularios y configuraciones de temas cambian con poca frecuencia y son buenos candidatos para el almacenamiento en caché.

javascript

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

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

Usa webhooks para datos en tiempo real

En lugar de consultar la API repetidamente en busca de nuevas respuestas de formularios, configura webhooks para recibir notificaciones cuando lleguen envíos. Esto elimina solicitudes de consulta repetitivas y entrega datos más rápido.

Agrupa operaciones cuando sea posible

Si necesitas recuperar múltiples recursos, usa endpoints de lista con paginación en lugar de hacer solicitudes individuales para cada recurso. Una sola llamada a

GET/api/v1/forms?per_page=100

es mucho más eficiente que 100 llamadas separadas.

Monitorea el encabezado `X-RateLimit-Remaining`

Rastrea tu cuota restante y limita tus solicitudes antes de alcanzar el límite. Si X-RateLimit-Remaining cae por debajo de 10, considera agregar un pequeño retraso entre solicitudes.

Los límites de velocidad protegen la plataforma para todos los usuarios. Las aplicaciones que exceden consistentemente los límites de velocidad o intentan eludirlos pueden tener su acceso a la API suspendido. Si necesitas límites más altos, considera actualizar al plan Enterprise o contactar con soporte.

Actualización de tu límite de velocidad

Si necesitas más de 100 solicitudes por minuto, actualiza al plan Enterprise para obtener 500 solicitudes por minuto. Para límites superiores al Enterprise, contacta con nuestro equipo de ventas para discutir acuerdos personalizados.

Plan	Límite de velocidad	Precio
Pro	100 sol/min	$29/mes
Enterprise	500 sol/min	$99/mes
Personalizado	Negociable	Contactar ventas