Limite de chamadas por segundo (CPS)

Visão geral

Todas as contas da Vonage estão sujeitas a um limite de Chamadas por Segundo (CPS). Trata-se de um limite máximo para o número de novas chamadas de saída que podem ser iniciadas em qualquer intervalo contínuo de um segundo.

O limite padrão é de 3 CPS. Excedê-lo faz com que a plataforma rejeite as chamadas em excesso, normalmente com uma resposta 429 Too Many Requests (API REST) ou um código SIP 503 Service Unavailable (SIP Trunking).

Este guia explica o que é o CPS, por que ele existe, como os picos de tráfego causam falhas mesmo quando o volume total de chamadas é baixo e como projetar seu sistema para permanecer dentro do limite de forma confiável.

Por que a CPS existe

O CPS é um mecanismo de controle de taxa, não um limite de capacidade. Ele protege a estabilidade da plataforma e a alocação justa de recursos entre todas as contas. Mesmo uma conta de grande porte, com um limite elevado de chamadas simultâneas, pode saturar a infraestrutura de sinalização a jusante se iniciar um grande número de chamadas no mesmo segundo.

Como os picos de carga causam falhas

O erro mais comum é confundir o CPS médio com o CPS instantâneo.

Considere um sistema que precisa realizar 30 chamadas em 10 segundos (uma média de 3 CPS). Se essas 30 chamadas forem todas acionadas simultaneamente (por exemplo, um trabalho em lote é executado à meia-noite), todas elas chegam no primeiro segundo e 27 são rejeitadas.

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)

O limite é avaliado na borda da plataforma, e não calculado como média em uma janela definida por você. Sua limitação do lado do cliente deve impor a taxa antes que as chamadas cheguem à Vonage.

Melhores práticas gerais

Esses princípios se aplicam independentemente de você usar a Voice API (VAPI) ou o SIP Trunking.

1. Aplique o limite da sua parte, não da parte da Vonage. Não conte com a repetição de chamadas rejeitadas. Um erro 429/503 em grande escala gera seu próprio tráfego e prejudica o desempenho do seu sistema. Filtre as chamadas de saída antes que elas saiam da sua infraestrutura.

2. Utilize um algoritmo de “token-bucket” ou de “leaky-bucket”. Esses algoritmos foram desenvolvidos especificamente para a limitação de taxa. Um “token-bucket” é reabastecido a uma taxa fixa (por exemplo, 3 tokens por segundo), e cada chamada consome um token. Se o “bucket” estiver vazio, a chamada fica em espera. A maioria das linguagens de programação possui bibliotecas que implementam isso em poucas linhas de código.

3. O limite do CPS se aplica apenas às chamadas efetuadas — mas em todas as tipos de endpoint. As chamadas recebidas não estão sujeitas ao limite de CPS. No entanto, o limite para chamadas efetuadas se aplica de maneira uniforme, independentemente do tipo de terminal que esteja sendo discado. Todos os itens a seguir são contabilizados no seu orçamento de CPS:

   • phone — chamada efetuada para um número da rede PSTN
   • sip — chamada para um URI SIP ou um tronco SIP
   • websocket — cada conexão WebSocket de saída estabelecida como um trecho de chamada conta como uma chamada para fins de CPS
   • app — chamada para um endpoint interno do aplicativo do Client SDK/WebRTC

   Se a sua aplicação combinar tipos de endpoints no mesmo segundo — por exemplo, fazer uma ligação telefônica e, ao mesmo tempo, abrir uma conexão WebSocket —, ambos serão contabilizados. Projete seu limitador para monitorar a taxa combinada de tráfego de saída em todos os tipos de endpoints, e não por tipo.

4. Adicione jitter ao tentar novamente. Se você for tentar novamente (por exemplo, em caso de erros transitórios de rede), adicione um jitter aleatório (50–500 ms) ao backoff. Tentativas sincronizadas a partir de um conjunto de workers podem recriar o pico original.

5. Monitorar e emitir alertas sobre respostas 429/503. Acompanhe as taxas de rejeição em seu pipeline de registro. Um pico repentino indica que o tráfego a montante está em alta. Investigue a origem antes de solicitar um aumento do limite de CPS. Para monitorar o consumo de CPS em tempo real no momento da criação da chamada, use o return_cps_on_started parâmetro no seu POST /calls solicitação, ou returnCpsOnStarted em um NCCO connect ação. Consulte o Referência do Webhook da Voice API para mais detalhes.

SIP Trunking: Configuração do CPS no lado do PBX

Ao utilizar o SIP Trunking da Vonage, seu PBX é o remetente das mensagens SIP INVITE de saída. O limite de CPS deve ser aplicado no PBX antes que as chamadas cheguem ao gateway SIP da Vonage. A maioria das plataformas de PBX corporativas possui um recurso integrado de limitação de chamadas de saída ou de controle de ritmo de grupos de troncos.

Asterisk / FreePBX

No Asterisk, a limitação da taxa de chamadas de saída é implementada no nível do plano de discagem por meio do GROUP_COUNT(${EPOCH}) mecanismo que conta as chamadas iniciadas no segundo atual e mantém as chamadas excedentes em um ciclo 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)

O call-limit A opção em um terminal PJSIP controla o número máximo de canais simultâneos, e não a taxa. Ela é útil como um limite máximo, mas não como um controle de CPS.

Para obter mais informações, consulte Configuração do res_pjsip no Asterisk.

3CX

No 3CX, o CPS pode ser gerenciado por meio do Chamadas simultâneas configuração em Admin > Voz e bate-papo > [Trunk] > Guia “Opções”, que limita o número total de chamadas simultâneas pela linha troncal (entrantes e saídas combinadas). Definir esse valor de forma conservadora em relação ao seu limite do CPS da Vonage oferece uma proteção prática contra picos de tráfego. Observe que isso controla a capacidade de chamadas simultâneas, e não a taxa de iniciação de chamadas.

Para obter mais informações, consulte Opções de troncos SIP do 3CX para SIP Trunking.

Cisco Unified Communications Manager (CUCM)

Em um ambiente Cisco, o controle de largura de banda do CPS é gerenciado pelo Cisco Unified Border Element (CUBE), o controlador de borda de sessão que fica entre o CUCM e o gateway SIP da Vonage. No CUBE, use o call-spike threshold e voice service voip diretivas de limitação de taxa para garantir o CPS. No CUCM, os Locais oferecem controle de admissão de chamadas com base na largura de banda, o que determina a capacidade simultânea.

Para obter mais informações, consulte Guia de Configuração do Cisco CUBE.

Avaya Aura / Gerenciador de Sessões

Em ambientes Avaya, a aplicação das políticas CPS é gerenciada pelo Avaya Session Border Controller for Enterprise (SBCE), que oferece suporte a políticas de taxa de sinalização por tronco. O Avaya Session Manager gerencia o volume de chamadas por meio de Locais e Links de Entidade SIP, que determinam a capacidade simultânea por link.

Para obter mais informações, consulte Documentação do Avaya SBCE.

FreeSWITCH

O FreeSWITCH impõe um limite global de taxa de novas sessões por meio do sessions-per-second parâmetro em autoload_configs/switch.conf.xml. Isso limita a taxa de todas as novas etapas de chamadas em todo o sistema:

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

Para o controle de CPS por gateway, use o dialplan limit aplicativo para aplicar limitação de taxa a um recurso específico do gateway.

Para obter mais informações, consulte Configuração do FreeSWITCH no SBC/Controle de admissão de chamadas.

Voice API: Limitação das chamadas de saída

Ao realizar chamadas de saída por meio da Voice API, seu aplicativo controla diretamente a taxa de POST /calls solicitações. A plataforma retornará HTTP 429 se você ultrapassar seu limite de CPS na primeira POST /calls solicitação. No entanto, as chamadas subsequentes iniciadas por meio de ações de conexão no NCCO são processadas de forma assíncrona — caso excedam o limite do CPS, nenhum código 429 é retornado à solicitação original. Em vez disso, um rejected A chamada de retorno de status é enviada para a URL do seu evento com o detail campo definido como 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"
}

Implementação de um mecanismo simples de limitação de tráfego com o modelo “token-bucket”

O exemplo a seguir mostra como despachar um lote de chamadas de saída respeitando o limite do CPS. Ele utiliza um padrão “leaky bucket” simples com asyncio (Python), que é representativo da lógica necessária em qualquer linguagem de programação.

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

Pontos-chave

• interval = 1.0 / CPS_LIMIT garante exatamente um intervalo de chamada a cada ~333 ms a 3 CPS. Ajuste esse valor quando seu limite for aumentado.
• O jitter impede que todos os workers em uma implantação multiprocessos sejam acionados exatamente no mesmo milésimo de segundo.
• asyncio.gather permite que todas as chamadas fiquem em andamento simultaneamente após serem despachadas — a limitação se aplica apenas à taxa de iniciação, e não à duração.
• Para sistemas multiprocesso ou distribuídos, o token bucket deve ser compartilhado (por exemplo, por meio do Redis com um script em Lua ou um sidecar dedicado para limitação de taxa). Um bucket por processo excederá o limite da sua conta se você executar vários workers.

Tratamento de 429 respostas

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

Utilize o backoff exponencial com jitter (em vez de um intervalo de espera fixo) para evitar tempestades de tentativas sincronizadas entre os workers.

Accounts with Subaccounts: Hierárquica aplicação do CPS

Esta seção só é relevante se você utilizar Subaccounts da Vonage (chaves de API secundárias). Se sua integração utilizar uma única chave de API principal, você pode pular esta seção. Consulte o Visão geral da API de Subaccounts para o gerenciamento geral das Subaccounts.

Como funciona o modelo de duas camadas

O CPS é aplicado em dois níveis simultaneamente:

1. Limite da subconta: cada chave de sub-API individual possui seu próprio limite CPS. O tráfego proveniente dessa chave não pode excedê-lo.
2. Limite da chave de API principal: O CPS agregado de todas as chaves (principal + todas as subcontas) é limitado pela configuração de CPS da chave de API principal. Trata-se de um limite máximo rígido para o tráfego total da conta.

Ambos os limites se aplicam simultaneamente. Uma chamada é rejeitada caso seja atingido o limite da subconta ou o limite máximo da chave principal.

Exemplo

A cada segundo, a subchave 1 pode disparar no máximo 10 chamadas, a subchave 2, no máximo 10 chamadas, e a subchave 3, no máximo 10 chamadas; porém, o total combinado das três (mais quaisquer chamadas na própria chave principal) não pode exceder 20 CPS. A soma dos limites das subcontas (30) é irrelevante — o limite principal sempre prevalece.

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          │
└─────────────────────────────────────────────┘

O que isso significa na prática

Subaccounts share the account's budget. If you execute multiple workloads or serve multiple customers on separate subchaves, they will compete for the same key allowance. A spike in traffic on one subaccount can cause rejections on all other accounts, even if each individual subaccount is within its own limit.

Tanto as chamadas por SIP Trunking quanto as chamadas VAPI são contabilizadas no mesmo limite combinado. Uma combinação de SIP INVITE mensagens e POST /calls Todas as solicitações REST utilizam o mesmo limite máximo de chave principal. Se você usar os dois produtos na mesma hierarquia de Accounts, defina sua capacidade de acordo com isso.

O limite da chave principal é o número que você deve observar. Ao solicitar um aumento do CPS, certifique-se de aumentar o limite da chave API principal (aumentar apenas o limite de uma subconta, mantendo o limite principal inalterado, não terá efeito algum se o limite principal já for a restrição determinante).

Projeto para a subconta CPS

• Defina o limite máximo da conta principal de forma que corresponda ao pico da demanda agregada, e não à soma dos limites das subcontas. Se for improvável que todas as subcontas atinjam seus limites ao mesmo tempo, um limite máximo da conta principal inferior ao total dos limites das subcontas é aceitável, mas é preciso considerar o pior cenário possível.
• Defina os limites das subcontas de forma deliberada. Mantenha os limites individuais das subcontas proporcionais à parcela de tráfego esperada para cada carga de trabalho. Limites excessivamente altos nas subcontas criam uma falsa sensação de margem de segurança.
• Aplique a limitação por subconta no código, e não apenas no nível da chave principal. Mesmo que o limite principal seja generoso, uma subconta sem limitação pode prejudicar as outras ao consumir uma parcela desproporcional.

Solicitação de um limite mais alto do CPS

O limite padrão de 3 CPS é suficiente para a maioria dos casos de uso em desenvolvimento e produção de baixo volume. Para campanhas de saída de alto volume, implantações em centrais de atendimento ou troncos SIP que atendem a grandes instalações de PBX, está disponível um limite mais alto. Entre em contato com a Vonage de acordo com o seu caso de uso e os volumes de chamadas previstos. A Vonage avaliará a solicitação e aumentará o limite da sua Account, o que geralmente é refletido em até um dia útil.

Leitura complementar

• Voice API: fazer uma chamada de saída
• Introdução ao SIP Trunking
• Limites de taxa da API