Límite de llamadas por segundo (CPS)

Visión general

Todas las cuentas de Vonage están sujetas a un límite de llamadas por segundo (CPS). Se trata de un límite máximo que establece el número de nuevas llamadas salientes que se pueden iniciar en cualquier intervalo de un segundo.

El límite predeterminado es de 3 CPS. Si se supera, la plataforma rechaza las llamadas excedentes, normalmente con una respuesta 429 «Too Many Requests» (API REST) o un código SIP 503 «Service Unavailable» (SIP Trunking).

En esta guía se explica qué es el CPS, por qué existe, cómo los picos de tráfico provocan fallos incluso cuando el volumen total de llamadas es bajo y cómo diseñar el sistema para mantenerse dentro del límite de forma fiable.

Por qué existe CPS

El CPS es un mecanismo de control de velocidad, no un límite de capacidad. Protege la estabilidad de la plataforma y garantiza una asignación equitativa de recursos entre todas las cuentas. Incluso una cuenta de gran tamaño con un límite elevado de llamadas simultáneas puede saturar la infraestructura de señalización posterior si inicia un gran número de llamadas en el mismo segundo.

Cómo las ráfagas provocan fallos

El error más habitual es confundir el CPS medio con el CPS instantáneo.

Imaginemos un sistema que tiene que realizar 30 llamadas en 10 segundos (una media de 3 CPS). Si esas 30 llamadas se activan todas a la vez (por ejemplo, si un trabajo por lotes se ejecuta a medianoche), llegan todas en el primer segundo y 27 de ellas son rechazadas.

Without throttling (30 calls, all fired at t=0):
t=0s  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  ← 30 attempted, 27 rejected
t=1s  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
...

With throttling (30 calls, 3 per second):
t=0s  ▓▓▓  ← 3 accepted
t=1s  ▓▓▓  ← 3 accepted
t=2s  ▓▓▓  ← 3 accepted
...
(all 30 succeed)

El límite se evalúa en el extremo de la plataforma, no se calcula como media en una ventana que controles. Tu sistema de limitación del lado del cliente debe garantizar el cumplimiento de la tasa antes de que las llamadas lleguen a Vonage.

Prácticas recomendadas generales

Estos principios se aplican independientemente de si utilizas la Voice API (VAPI) o SIP Trunking.

1. Aplica el límite por tu parte, no por parte de Vonage. No confíes en volver a intentar las llamadas rechazadas. Un error 429/503 a gran escala genera su propio tráfico y deteriora el rendimiento de tu sistema. Filtra las llamadas salientes antes de que salgan de tu infraestructura.

2. Utiliza un algoritmo de «cubo de fichas» o de «cubo con agujeros». Estos algoritmos están diseñados específicamente para la limitación de tasa. Un «token bucket» se rellena a una tasa fija (por ejemplo, 3 tokens por segundo) y cada llamada consume un token. Si el «token bucket» está vacío, la llamada queda en espera. La mayoría de los lenguajes de programación cuentan con bibliotecas que implementan esto en unas pocas líneas de código.

3. El límite de CPS se aplica únicamente a las llamadas salientes, aunque en todas las tipos de puntos finales. Las llamadas entrantes no están sujetas al límite de CPS. Sin embargo, el límite de llamadas salientes se aplica de forma uniforme, independientemente del tipo de terminal al que se llame. Todos los siguientes elementos se deducen de tu presupuesto de CPS:

   • phone — llamada saliente a un número de la red pública de telefonía (PSTN)
   • sip — llamada a un URI SIP o a un enlace SIP
   • websocket — Cada conexión WebSocket saliente establecida como tramo de llamada cuenta como una llamada a efectos del CPS
   • app — llamada a un punto final integrado en la aplicación del Client SDK/WebRTC

   Si tu aplicación combina distintos tipos de puntos finales en el mismo segundo —por ejemplo, realizar una llamada telefónica y abrir al mismo tiempo una conexión WebSocket—, ambos cuentan. Diseña tu sistema de limitación para que controle la tasa de salida combinada de todos los tipos de puntos finales, y no por tipo.

4. Añade fluctuación al volver a intentarlo. Si decides volver a intentarlo (por ejemplo, en caso de errores transitorios de red), añade una variación aleatoria (50-500 ms) al tiempo de espera. Los reintentos sincronizados desde un grupo de trabajadores pueden recrear la ráfaga original.

5. Supervisar y enviar alertas sobre las respuestas 429/503. Realiza un seguimiento de las tasas de rechazo en tu proceso de registro. Un pico repentino indica que el tráfico en las etapas anteriores está experimentando picos de tráfico. Investiga el origen antes de solicitar un aumento del límite de CPS. Para supervisar el consumo de CPS en tiempo real en el momento de la creación de la llamada, utiliza el return_cps_on_started parámetro en tu POST /calls solicitud, o returnCpsOnStarted en un NCCO connect acción. Consulta el Referencia de webhooks de la Voice API Para más información.

SIP Trunking: Configuración de CPS en el lado de la centralita

Al utilizar el servicio de SIP Trunking de Vonage, tu centralita es la encargada de enviar los mensajes SIP INVITE salientes. El límite de CPS debe aplicarse en la centralita antes de que las llamadas lleguen a la pasarela SIP de Vonage. La mayoría de las plataformas de centralitas empresariales cuentan con una función integrada de limitación de llamadas salientes o de control de ritmo de grupos de troncales.

Asterisk / FreePBX

En Asterisk, la limitación de la velocidad de las llamadas salientes se implementa a nivel de plan de marcación mediante el GROUP_COUNT(${EPOCH}) mecanismo que cuenta las llamadas iniciadas durante el segundo actual y mantiene las llamadas sobrantes en un bucle de espera:

[globals]
calls_per_sec=3

[OUTBOUND]
exten => _X.,1,Set(GROUP()=${EPOCH})
same => n,GotoIf($[${GROUP_COUNT(${EPOCH})}>${calls_per_sec}]?DELAY,${EXTEN},1)
same => n,Dial(PJSIP/vonage-trunk/${EXTEN})

[DELAY]
exten => _X.,1,Wait(0.5)
same => n,Goto(OUTBOUND,${EXTEN},1)

El call-limit La opción de un terminal PJSIP controla el número máximo de canales simultáneos, no la velocidad. Resulta útil como límite máximo, pero no como control de CPS.

Para más información, consulte Configuración de res_pjsip en Asterisk.

3CX

En 3CX, el CPS se puede gestionar mediante el Llamadas simultáneas configuración en Admin > Voz y chat > [Trunk] > pestaña «Opciones», que limita el número total de llamadas simultáneas a través del canal (entrantes y salientes combinadas). Establecer este valor de forma conservadora en relación con el límite del CPS de Vonage ofrece una protección práctica contra los picos de tráfico. Ten en cuenta que esto controla la capacidad de llamadas simultáneas, no la tasa de iniciación de llamadas.

Para más información, consulte Opciones de SIP Trunking de 3CX.

Cisco Unified Communications Manager (CUCM)

En un entorno de Cisco, la limitación de CPS la gestiona el Cisco Unified Border Element (CUBE), el controlador de borde de sesión que se encuentra entre el CUCM y la pasarela SIP de Vonage. En el CUBE, utiliza el call-spike threshold y voice service voip Directivas de limitación de velocidad para aplicar el CPS. En CUCM, las ubicaciones proporcionan un control de admisión de llamadas basado en el ancho de banda, lo que regula la capacidad simultánea.

Para más información, consulte Guía de configuración de Cisco CUBE.

Avaya Aura / Gestor de sesiones

En entornos Avaya, la aplicación de CPS corre a cargo del Avaya Session Border Controller for Enterprise (SBCE), que admite políticas de velocidad de señalización por línea troncal. Avaya Session Manager gestiona el volumen de llamadas a través de «Locations» y «SIP Entity Links», que regulan la capacidad simultánea por enlace.

Para más información, consulte Documentación de Avaya SBCE.

FreeSWITCH

FreeSWITCH aplica un límite global de frecuencia de nuevas sesiones a través del sessions-per-second parámetro en autoload_configs/switch.conf.xml. Esto limita la tarifa de todos los tramos de llamada nuevos en todo el sistema:

<!-- autoload_configs/switch.conf.xml -->
<param name="sessions-per-second" value="3"/>
<param name="max-sessions" value="1000"/>

Para el control de CPS por pasarela, utiliza el dialplan limit solicitud para aplicar una limitación de tasa a un recurso de pasarela específico.

Para más información, consulte Configuración de FreeSWITCH en un SBC / Control de admisión de llamadas.

Voice API: limitación de las llamadas salientes

Al realizar llamadas salientes a través de la Voice API, tu aplicación controla directamente la velocidad de POST /calls solicitudes. La plataforma devolverá HTTP 429 si superas tu límite de CPS en la primera POST /calls solicitud. Sin embargo, las llamadas posteriores iniciadas mediante acciones «connect» en el NCCO se procesan de forma asíncrona; si estas superan el límite del CPS, no se devuelve un código 429 a la solicitud original. En su lugar, un rejected La llamada de retorno de estado se envía a tu URL de eventos con el detail con el valor throttled:

{
  "from": "442079460000",
  "to": "447700900000",
  "detail": "throttled, see knowledge article https://api.support.vonage.com/hc/en-us/articles/207100288",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "status": "rejected",
  "direction": "outbound",
  "timestamp": "2020-01-01T12:00:00.000Z"
}

Implementación de un sistema sencillo de limitación de tráfico con «token-bucket»

El ejemplo siguiente muestra cómo enviar un lote de llamadas salientes respetando el límite de CPS. Utiliza un patrón sencillo de «leaky bucket» con asyncio (Python), que es representativo de la lógica necesaria en cualquier lenguaje de programación.

import asyncio
import httpx
import random
import time

VONAGE_API_URL = "https://api.nexmo.com/v1/calls"
CPS_LIMIT = 3          # Match your account's CPS limit
JITTER_MS  = 100       # Add up to 100 ms of random jitter per call

async def place_call(client: httpx.AsyncClient, call_payload: dict) -> dict:
    response = await client.post(VONAGE_API_URL, json=call_payload)
    response.raise_for_status()
    return response.json()

async def dispatch_calls(call_payloads: list[dict]):
    """
    Dispatch a batch of outbound calls at a controlled rate.
    Fires CPS_LIMIT calls per second, with per-call jitter.
    """
    interval = 1.0 / CPS_LIMIT          # seconds between each call slot
    async with httpx.AsyncClient(headers={"Authorization": "Bearer <JWT>"}) as client:
        tasks = []
        for i, payload in enumerate(call_payloads):
            # Sleep until the next call slot, plus random jitter
            jitter = random.uniform(0, JITTER_MS / 1000)
            await asyncio.sleep((interval if i > 0 else 0) + jitter)
            task = asyncio.create_task(place_call(client, payload))
            tasks.append(task)
            print(f"[{time.strftime('%H:%M:%S')}] Dispatched call {i+1}/{len(call_payloads)}")
        results = await asyncio.gather(*tasks, return_exceptions=True)
        failures = [r for r in results if isinstance(r, Exception)]
        if failures:
            print(f"{len(failures)} call(s) failed: {failures}")
        return results

# Example usage
if __name__ == "__main__":
    calls = [
        {
            "to":   [{"type": "phone", "number": "14155550100"}],
            "from": {"type": "phone", "number": "14155550199"},
            "ncco": [{"action": "talk", "text": "Hello from Vonage."}]
        }
        # ...
        # repeat for each call
    ] * 30  # 30 calls total
    asyncio.run(dispatch_calls(calls))

Puntos clave

• interval = 1.0 / CPS_LIMIT Garantiza exactamente un intervalo de llamada cada ~333 ms a 3 CPS. Ajústalo cuando se aumente tu límite.
• El «jitter» evita que todos los trabajadores de una implementación multiproceso se activen en el mismo milisegundo.
• asyncio.gather permite que todas las llamadas estén activas simultáneamente una vez enviadas; la limitación solo se aplica a la frecuencia de inicio, no a la duración.
• En el caso de los sistemas multiproceso o distribuidos, el «token bucket» debe ser compartido (por ejemplo, a través de Redis con un script de Lua o un «sidecar» dedicado a la limitación de tasa). Un «token bucket» por proceso superará el límite de tu cuenta si ejecutas varios trabajadores.

Gestión de 429 respuestas

async def place_call_with_retry(client, payload, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await place_call(client, payload)
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429 and attempt < max_retries - 1:
                backoff = (2 ** attempt) + random.uniform(0, 1)
                print(f"Rate limited. Retrying in {backoff:.2f}s...")
                await asyncio.sleep(backoff)
            else:
                raise

Utiliza un retroceso exponencial con fluctuación (en lugar de un tiempo de espera fijo) para evitar tormentas de reintentos sincronizados entre los trabajadores.

Accounts with Subaccounts: application of hierarchical CPS enforcement

Esta sección solo es relevante si utilizas Subaccounts de Vonage (claves API secundarias). Si tu integración utiliza una única clave API principal, puedes saltarte esta sección. Consulta la Descripción general de la API de Subaccounts para la gestión general de las Subaccounts.

Cómo funciona el modelo de dos capas

El CPS se aplica en dos niveles simultáneamente:

1. Límite de cuenta: cada clave de sub-API individual tiene su propio límite de CPS. El tráfico procedente de dicha clave no puede superarlo.
2. Límite de la clave API principal: el CPS total de todas las claves (la principal y todas las subcuentas) está limitado por la configuración de CPS de la clave API principal. Se trata de un límite máximo estricto para el tráfico total de la cuenta.

Ambos límites se aplican simultáneamente. Una llamada se rechaza si se alcanza el límite de la subcuenta o el límite máximo de la clave principal.

Ejemplo

En cualquier momento dado, la subclave 1 puede generar como máximo 10 llamadas, la subclave 2 como máximo 10 llamadas y la subclave 3 como máximo 10 llamadas, pero el total combinado de las tres (más cualquier llamada de la propia clave principal) no puede superar las 20 CPS. La suma de los límites de las subcuentas (30) es irrelevante: siempre prevalece el límite máximo principal.

Main API key cap: 20 CPS
┌─────────────────────────────────────────────┐
│  Sub-key 1  │  Sub-key 2  │  Sub-key 3      │
│  ≤ 10 CPS   │  ≤ 10 CPS   │  ≤ 10 CPS       │
│                                             │
│  Combined total must stay ≤ 20 CPS          │
└─────────────────────────────────────────────┘

Qué significa esto en la práctica

Subaccounts share the budget of the main account. If you run multiple workloads or manage multiple customers in separate subclaves, these compete for the same main key limit. A traffic spike in a subaccount can cause rejections in all the others, even if each individual subaccount is within its own limit.

Tanto las llamadas de SIP Trunking como las de VAPI se contabilizan en el mismo límite combinado. Una combinación de SIP INVITE mensajes y POST /calls Todas las solicitudes REST se nutren del mismo límite máximo de clave principal. Si utilizas ambos productos dentro de la misma jerarquía de Accounts, diseña tu capacidad en consecuencia.

El límite de la clave principal es la cifra a tener en cuenta. Cuando solicites un aumento de CPS, asegúrate de que estás aumentando el límite de la clave API principal (aumentar únicamente el límite de una subcuenta sin modificar el límite principal no tendrá ningún efecto si este último ya es la restricción determinante).

Diseño para la subcuenta CPS

• Establece el límite máximo de la cuenta principal de modo que se ajuste a la demanda máxima agregada, y no a la suma de los límites de las subcuentas. Si es poco probable que todas las subcuentas se saturen a la vez, basta con que el límite máximo de la cuenta principal sea inferior a la suma de los límites de las subcuentas, pero ten en cuenta el peor de los casos.
• Establece los límites de las subcuentas de forma deliberada. Mantén los límites individuales de las subcuentas proporcionales al volumen de tráfico que esperas de cada carga de trabajo. Unos límites excesivos en las subcuentas dan una falsa sensación de margen de maniobra.
• Aplica la limitación por subcuenta en el código, no solo a nivel de la clave principal. Aunque el límite principal sea generoso, una subcuenta sin limitación puede agotar los recursos de las demás al consumir una parte desproporcionada.

Solicitud de un límite más alto de CPS

El límite predeterminado de 3 CPS es suficiente para la mayoría de los casos de uso relacionados con el desarrollo y la producción a pequeña escala. Para campañas de salida a gran escala, implementaciones en centros de atención al cliente o troncales SIP que dan servicio a grandes instalaciones de centralitas, se ofrece un límite más alto. Ponte en contacto con Vonage en función de su caso de uso y del volumen de llamadas previsto. Vonage evaluará la solicitud y le asignará un límite más alto en su Account, lo que suele hacerse efectivo en el plazo de un día laborable.

Lecturas complementarias

• Voice API: Realizar una llamada saliente
• Introducción a SIP Trunking
• Límites de rate de la API