Límites de solicitudes

Certivant aplica un límite de solicitudes por minuto para proteger la plataforma de clientes descontrolados y de usos abusivos. Si se mantiene por debajo del límite, nunca verá limitaciones; si lo supera, recibirá un 429 con cabeceras que le indican exactamente cuándo reintentar.

El límite

Su techo por minuto lo define su plan. El operador de la plataforma también puede conceder una excepción por cliente, que siempre queda limitada por el tope del plan. El número efectivo es el que indica la cabecera X-RateLimit-Limit en cada respuesta: léala en lugar de fijar un valor en el código.

Techos por defecto según el plan

Estos son valores por defecto: el operador de su plataforma puede ajustar el tope de cada plan y conceder a su organización un límite por cliente más alto (hasta el tope del plan). Puede ver el límite efectivo de su organización, en modo de solo lectura, en el panel, en KYC → Desarrollador.

Si necesita un techo más alto para el tráfico de producción, pida a su contacto de cuenta (o, en instalaciones autoalojadas, a su operador de la plataforma) que aumente el tope de su plan o su límite por cliente.

Cabeceras de respuesta (en todas las respuestas autenticadas)

Cada respuesta correcta incluye el estado actual del límite de solicitudes:

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42
Content-Type: application/json

{ "data": [...], "pagination": {...} }

Lea estas cabeceras en su cliente para reducir la frecuencia de forma proactiva: no espere a recibir un 429 si ve X-RateLimit-Remaining: 3.

La respuesta 429

Cuando supera el límite, la siguiente solicitud devuelve:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 18
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Max 120 requests per 60s. Retry in 18s."
  }
}

X-RateLimit-Reset le indica exactamente cuánto tiempo debe esperar. Úselo en lugar de estimarlo.

Estrategia de reintento

El manejador correcto más sencillo:

async function withRateLimit<T>(fn: () => Promise<Response>): Promise<T> {
  while (true) {
    const res = await fn();
    if (res.status !== 429) {
      if (!res.ok) throw await readError(res);
      return res.json() as Promise<T>;
    }
    const retryAfterSec = Number(res.headers.get("X-RateLimit-Reset") ?? 60);
    await sleep(retryAfterSec * 1000 + 100); // pad by 100ms for clock skew
  }
}

Tres propiedades que conviene mantener:

1. Respete X-RateLimit-Reset. Esperar menos solo provoca que vuelva a alcanzar el límite.
2. Añada unos 100 ms de margen para compensar el desfase de reloj entre su máquina y el borde de Certivant.
3. Limite sus reintentos si la solicitud no es crítica. Insistir durante 5 minutos en una llamada de listado no urgente desperdicia recursos en ambos extremos.

Diseñar en función del límite

El mayor ahorro procede de usar webhooks. La principal causa de los tickets de soporte del tipo «estoy alcanzando el límite de solicitudes» son las integraciones que consultan periódicamente los cambios de estado: no lo haga, configure en su lugar los webhooks.

Comportamiento ante ráfagas

El límite se aplica como ventana fija: la primera solicitud inicia un contador de 60 segundos, y cada solicitud cuenta contra su techo hasta que la ventana se reinicia. Distribuya el tráfico sostenido de manera uniforme en lugar de consumir todo el presupuesto del minuto en los primeros segundos.

Si tiene un patrón de ráfagas conocido (por ejemplo, un trabajo por lotes diario que procesa 500 registros), espacie las llamadas:

for (const record of records) {
  await processOne(record);
  await sleep(500); // 2 req/s — comfortably under typical ceilings
}

Qué ocurre si Redis no está disponible

Si la instancia de Redis del límite de solicitudes no está disponible temporalmente, Certivant falla en abierto: no bloquea su tráfico. Verá respuestas 2xx normales sin las cabeceras X-RateLimit-*. Cuando Redis vuelva a estar disponible, se reanuda la aplicación normal del límite. Esto significa que una caída de Redis en nuestro lado no interrumpe su integración.

Los webhooks van por separado

El límite de solicitudes se aplica a sus llamadas salientes a Certivant. Las entregas de webhooks entrantes desde Certivant a su endpoint no consumen ninguna cuota. No existe un «límite de webhooks» del que deba preocuparse.

Endpoints públicos

Los endpoints que no requieren clave de API (GET /api/status, GET /api/kyc/public/status, los endpoints de envío de formularios) tienen un límite por IP independiente de 60 solicitudes por minuto. Se aplica a la dirección IP del llamador, no a una clave de API. Se ha fijado de forma conservadora porque estos endpoints son accesibles sin autenticación; si su interfaz para solicitantes está alcanzando ese límite, encamine las llamadas a través de su propio backend para que compartan una IP bajo su control.