Limite d'appels par seconde (CPS)

Vue d'ensemble

Chaque compte Vonage est soumis à une limite de « appels par seconde » (CPS). Il s'agit d'un plafond fixant le nombre de nouveaux appels sortants pouvant être lancés au cours d'une fenêtre glissante d'une seconde.

La limite par défaut est de 3 CPS. Tout dépassement de cette limite entraîne le rejet des appels excédentaires par la plateforme, généralement accompagné d’une réponse 429 « Too Many Requests » (API REST) ou d’un code SIP 503 « Service Unavailable » (SIP Trunking).

Ce guide explique ce qu’est le CPS, pourquoi il existe, comment les pics de trafic peuvent entraîner des défaillances même lorsque votre volume total d’appels est faible, et comment concevoir votre système pour rester en deçà de la limite de manière fiable.

Pourquoi le CPS existe-t-il ?

Le CPS est un mécanisme de contrôle du débit, et non une limite de capacité. Il garantit la stabilité de la plateforme et une répartition équitable des ressources entre tous les comptes. Même un compte important, disposant d'une limite élevée d'appels simultanés, peut saturer l'infrastructure de signalisation en aval s'il lance un grand nombre d'appels au cours d'une même seconde.

Comment les pics de trafic provoquent des pannes

L'erreur la plus courante consiste à confondre le CPS moyen et le CPS instantané.

Prenons l'exemple d'un système qui doit passer 30 appels en 10 secondes (soit une moyenne de 3 appels par seconde). Si ces 30 appels sont tous déclenchés simultanément (par exemple, lors de l'exécution d'un traitement par lots à minuit), ils arrivent tous au cours de la première seconde et 27 d'entre eux sont rejetés.

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)

La limite est évaluée au niveau de la plateforme, et non calculée en moyenne sur une fenêtre que vous contrôlez. Votre système de régulation côté client doit appliquer ce débit avant que les appels n'atteignent Vonage.

Bonnes pratiques générales

Ces principes s'appliquent, que vous utilisiez la Voice API (VAPI) ou le SIP Trunking.

1. C'est à vous d'appliquer la limite, pas à Vonage. Ne comptez pas sur la reprise des appels rejetés. Un code d'erreur 429/503 à grande échelle génère son propre trafic et nuit aux performances de votre système. Filtrez les appels sortants avant qu'ils ne quittent votre infrastructure.

2. Utilisez un algorithme de type « token-bucket » ou « leaky-bucket ». Ces algorithmes sont spécialement conçus pour la limitation de débit. Un « token bucket » se recharge à un débit fixe (par exemple, 3 jetons par seconde), et chaque appel consomme un jeton. Si le « bucket » est vide, l'appel est mis en attente. La plupart des langages disposent de bibliothèques permettant de mettre en œuvre ce mécanisme en quelques lignes de code.

3. La limite CPS s'applique uniquement aux appels sortants — mais pour tous les types de points de terminaison. Les appels entrants ne sont pas soumis à la limite CPS. En revanche, la limite pour les appels sortants s’applique de manière uniforme, quel que soit le type de terminal appelé. Les éléments suivants sont tous pris en compte dans le calcul de votre budget CPS :

   • phone — appel sortant vers un numéro du réseau téléphonique public (PSTN)
   • sip — appel vers une URI SIP ou une liaison SIP
   • websocket — chaque connexion WebSocket sortante établie en tant que segment d'appel est comptabilisée comme un appel dans le cadre du CPS
   • app — appel vers un point de terminaison intégré à l'application via le Client SDK/WebRTC

   Si votre application combine plusieurs types de points de terminaison au cours d'une même seconde (par exemple, en passant un appel téléphonique tout en ouvrant simultanément une connexion WebSocket), les deux opérations sont prises en compte. Concevez votre système de limitation de débit de manière à suivre le débit sortant cumulé pour l'ensemble des types de points de terminaison, et non par type.

4. Ajouter un jitter lors des nouvelles tentatives. Si vous effectuez une nouvelle tentative (par exemple en cas d'erreurs réseau temporaires), ajoutez un jitter aléatoire (50 à 500 ms) au délai de recul. Les nouvelles tentatives synchronisées provenant d'un pool de travailleurs peuvent recréer la rafale d'origine.

5. Surveiller et générer des alertes en cas de réponses 429/503. Suivez les taux de rejet dans votre pipeline de journalisation. Une hausse soudaine indique que le trafic en amont connaît un pic. Identifiez-en la source avant de demander une augmentation de la limite de CPS. Pour surveiller en temps réel la consommation de CPS au moment de la création d'un appel, utilisez la return_cps_on_started paramètre dans votre POST /calls demande, ou returnCpsOnStarted dans un NCCO connect action. Voir le Référence sur les webhooks de la Voice API pour plus de détails.

SIP Trunking : configuration CPS côté PBX

Lorsque vous utilisez le service SIP Trunking de Vonage, c'est votre PBX qui émet les messages SIP INVITE sortants. La limite CPS doit être appliquée au niveau du PBX avant que les appels n'atteignent la passerelle SIP de Vonage. La plupart des plateformes PBX d'entreprise intègrent une fonctionnalité de régulation des appels sortants ou de limitation du débit par groupe de liaisons.

Asterisk / FreePBX

Dans Asterisk, la limitation du débit des appels sortants est mise en œuvre au niveau du plan de numérotation à l'aide de la commande GROUP_COUNT(${EPOCH}) mécanisme qui compte les appels lancés au cours de la seconde en cours et place les appels excédentaires dans une boucle d'attente :

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

Les call-limit Cette option, sur un terminal PJSIP, permet de contrôler le nombre maximal de canaux simultanés, et non le débit. Elle est utile pour fixer une limite maximale, mais ne permet pas de contrôler le CPS.

Pour plus d'informations, voir Configuration de res_pjsip dans Asterisk.

3CX

Dans 3CX, la gestion du CPS s'effectue à l'aide de la Appels simultanés paramètre sous Admin > Voix et chat > [Trunk] > Onglet « Options », qui limite le nombre total d’appels simultanés transitant par la ligne réseau (appels entrants et sortants combinés). Définir cette valeur de manière prudente par rapport à votre limite CPS Vonage constitue une protection efficace contre les pics de trafic. Notez que ce paramètre contrôle la capacité d’appels simultanés, et non le débit d’initiation des appels.

Pour plus d'informations, voir Options de SIP Trunking 3CX.

Cisco Unified Communications Manager (CUCM)

Dans un environnement Cisco, la régulation du débit CPS est gérée par le Cisco Unified Border Element (CUBE), le contrôleur de frontière de session situé entre le CUCM et la passerelle SIP Vonage. Sur le CUBE, utilisez la commande call-spike threshold et voice service voip directives de limitation de débit pour assurer le respect du CPS. Dans CUCM, les sites assurent le contrôle d'admission des appels en fonction de la bande passante, ce qui régit la capacité simultanée.

Pour plus d'informations, voir Guide de configuration de Cisco CUBE.

Avaya Aura / Gestionnaire de sessions

Dans les environnements Avaya, l'application des politiques CPS est gérée par le contrôleur de session en périphérie pour entreprises (SBCE) d'Avaya, qui prend en charge les politiques de débit de signalisation par ligne. Avaya Session Manager gère le volume d'appels via les « Locations » et les « SIP Entity Links », qui régissent la capacité simultanée par liaison.

Pour plus d'informations, voir Documentation Avaya SBCE.

FreeSWITCH

FreeSWITCH applique une limite globale du nombre de nouvelles sessions par le biais du sessions-per-second paramètre dans autoload_configs/switch.conf.xml. Cela limite le débit de tous les nouveaux segments d'appel à l'échelle du système :

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

Pour le contrôle CPS par passerelle, utilisez le dialplan limit application permettant d'appliquer une limitation de débit à une ressource de passerelle spécifique.

Pour plus d'informations, voir Configuration du SBC FreeSWITCH / Contrôle d'admission des appels.

Voice API : limitation des appels sortants

Lorsque vous passez des appels sortants via la Voice API, votre application contrôle directement la vitesse de POST /calls requêtes. La plateforme renverra une réponse HTTP 429 si vous dépassez votre limite CPS lors de la première POST /calls requête. Cependant, les appels suivants lancés via des actions « connect » dans le NCCO sont traités de manière asynchrone : s’ils dépassent la limite CPS, aucun code 429 n’est renvoyé à la requête d’origine. À la place, un rejected La fonction de rappel de statut est transmise à votre URL d'événement avec le detail Le champ est fixé à 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"
}

Mise en place d'un système simple de limitation par « token bucket »

L'exemple ci-dessous montre comment répartir un lot d'appels sortants tout en respectant la limite CPS. Il utilise un modèle « leaky bucket » simple avec asyncio (Python), qui illustre bien la logique requise, quel que soit le langage utilisé.

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

Points clés

• interval = 1.0 / CPS_LIMIT garantit exactement un créneau d'appel toutes les ~333 ms à 3 CPS. Ajustez ce paramètre lorsque votre limite est augmentée.
• Le jitter empêche tous les workers d’un déploiement multiprocessus de se déclencher exactement à la même milliseconde.
• asyncio.gather permet à tous les appels d'être en cours simultanément une fois lancés — la limitation ne s'applique qu'au rythme de lancement, et non à la durée.
• Pour les systèmes multiprocessus ou distribués, le « token bucket » doit être partagé (par exemple via Redis avec un script Lua ou un sidecar dédié à la limitation de débit). Un « token bucket » propre à chaque processus dépassera la limite globale de votre compte si vous exécutez plusieurs workers.

Traitement de 429 réponses

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

Utilisez un délai d'attente exponentiel avec une variation aléatoire (et non un délai fixe) pour éviter les tempêtes de tentatives synchronisées entre les travailleurs.

Accounts comportant des Subaccounts : application hiérarchique du CPS

Cette section ne vous concerne que si vous utilisez des Subaccounts Vonage (clés API secondaires). Si votre intégration utilise une seule clé API principale, vous pouvez ignorer cette section. Consultez la Présentation de l'API des Subaccounts pour la gestion générale des Subaccounts.

Fonctionnement du modèle à deux couches

Le CPS est appliqué simultanément à deux niveaux :

1. Limite par compte : chaque clé API secondaire dispose de son propre plafond CPS. Le trafic provenant de cette clé ne peut pas dépasser ce plafond.
2. Limite de la clé API principale : le CPS cumulé de toutes les clés (principale + tous les sous-comptes) est plafonné par le paramètre CPS de la clé API principale. Il s'agit d'un plafond absolu pour le trafic total de l'account.

Ces deux limites s'appliquent simultanément. Une demande est rejetée dès que la limite du sous-compte ou le plafond de la clé principale est atteint.

Exemple

À tout moment, la sous-clé 1 peut déclencher au maximum 10 appels, la sous-clé 2 au maximum 10 appels et la sous-clé 3 au maximum 10 appels, mais le total combiné des trois (auxquels s'ajoutent les appels sur la clé principale elle-même) ne peut pas dépasser 20 CPS. La somme des limites des sous-comptes (30) n’a aucune incidence : c’est toujours le plafond principal qui prévaut.

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

Ce que cela signifie concrètement

Subaccounts partagent le budget du compte parent. Si vous exécutez plusieurs charges de travail ou gérez plusieurs clients sur des sous-clés distinctes, ceux-ci se disputent le même quota attribué à la clé principale. Un pic de trafic sur un sous-compte peut entraîner des rejets sur tous les autres, même si chaque sous-compte individuel reste dans les limites de son propre quota.

Les appels via le SIP Trunking et les appels VAPI sont tous deux pris en compte dans le même plafond global. Une combinaison de SIP INVITE messages et POST /calls Toutes les requêtes REST puisent dans la même limite maximale de clé principale. Si vous utilisez ces deux produits au sein d'une même hiérarchie d'Accounts, adaptez votre capacité en conséquence.

La limite de la clé principale est le chiffre à surveiller. Lorsque vous demandez une augmentation du CPS, veillez à augmenter la limite de la clé API principale (le fait d'augmenter uniquement la limite d'un sous-compte tout en laissant la limite principale inchangée n'aura aucun effet si cette dernière constitue déjà la contrainte limitante).

Conception pour les subaccounts CPS

• Définissez le plafond principal de manière à ce qu'il corresponde à la demande globale maximale, et non à la somme des limites des sous-comptes. Si les sous-comptes atteignent rarement tous leur limite en même temps, un plafond principal inférieur à la somme des sous-limites est acceptable, mais vous devez tout de même modéliser le scénario le plus défavorable.
• Définissez les limites des sous-comptes de manière réfléchie. Veillez à ce que les limites individuelles des sous-comptes soient proportionnelles à la part de trafic que vous prévoyez pour chaque charge de travail. Des limites de sous-comptes trop élevées donnent une fausse impression de marge de manœuvre.
• Appliquez la limitation par sous-compte dans le code, et pas seulement au niveau de la clé principale. Même si la limite globale est généreuse, un sous-compte non limité peut priver les autres de ressources en consommant une part disproportionnée.

Demande d'augmentation du plafond CPS

La limite par défaut de 3 CPS est suffisante pour la plupart des cas d'utilisation liés au développement et à la production à faible volume. Pour les campagnes sortantes à fort volume, les déploiements dans les centres d'appels ou les liaisons SIP desservant de grandes installations de PBX, une limite plus élevée est disponible. Contacter Vonage en fonction de votre cas d'utilisation et des volumes d'appels prévus. Vonage examinera votre demande et augmentera la limite de votre Account ; cette modification est généralement effective dans un délai d'un jour ouvré.

Pour en savoir plus

• Voice API : passer un appel sortant
• Premiers pas avec le SIP Trunking
• Limites de débit de l'API