Obergrenze für Anrufe pro Sekunde (CPS)

Übersicht

Für jeden Vonage-Account gilt ein Limit für Anrufe pro Sekunde (CPS). Dabei handelt es sich um eine Obergrenze dafür, wie viele neue ausgehende Anrufe innerhalb eines fortlaufenden Zeitfensters von einer Sekunde getätigt werden können.

Die Standardgrenze liegt bei 3 CPS. Wird diese überschritten, lehnt die Plattform die überzähligen Aufrufe ab, in der Regel mit einer 429-Antwort („Too Many Requests“) (REST-API) oder einem SIP-503-Fehler („Service Unavailable“) (SIP Trunking).

In diesem Leitfaden wird erläutert, was CPS ist, warum es existiert, wie Spitzenauslastungen selbst bei geringem Gesamtanrufaufkommen zu Ausfällen führen können und wie Sie Ihr System so gestalten können, dass die Grenzwerte zuverlässig eingehalten werden.

Warum es CPS gibt

CPS ist ein Mechanismus zur Ratenkontrolle und keine Kapazitätsbegrenzung. Er gewährleistet die Stabilität der Plattform und eine gerechte Ressourcenverteilung auf alle Accounts. Selbst ein großes Konto mit einem hohen Limit für gleichzeitige Anrufe kann die nachgelagerte Signalisierungsinfrastruktur überlasten, wenn es innerhalb einer Sekunde eine große Anzahl von Anrufen initiiert.

Wie Bursts zu Ausfällen führen

Der häufigste Fehler besteht darin, den Durchschnitts-CPS mit dem Momentan-CPS zu verwechseln.

Stellen Sie sich ein System vor, das innerhalb von 10 Sekunden 30 Anrufe tätigen muss (durchschnittlich 3 CPS). Wenn diese 30 Anrufe alle gleichzeitig ausgelöst werden (z. B. wenn um Mitternacht ein Batch-Job gestartet wird), gehen sie alle in der ersten Sekunde ein, und 27 davon werden abgelehnt.

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)

Das Limit wird am Plattformrand ausgewertet und nicht über ein von Ihnen festgelegtes Zeitfenster gemittelt. Ihre clientseitige Drosselung muss die Rate durchsetzen, bevor die Anrufe Vonage erreichen.

Allgemeine bewährte Vorgehensweisen

Diese Grundsätze gelten unabhängig davon, ob Sie die Voice API (VAPI) oder SIP Trunking nutzen.

1. Setzen Sie das Limit auf Ihrer Seite durch, nicht auf der von Vonage. Verlassen Sie sich nicht darauf, abgelehnte Anrufe erneut zu versuchen. Ein 429/503-Fehler in großem Umfang erzeugt eigenen Datenverkehr und beeinträchtigt die Leistung Ihres Systems. Leiten Sie ausgehende Anrufe ab, bevor sie Ihre Infrastruktur verlassen.

2. Verwenden Sie einen „Token-Bucket“- oder „Leaky-Bucket“-Algorithmus. Diese Algorithmen wurden speziell für die Ratenbegrenzung entwickelt. Ein Token-Bucket füllt sich mit einer festen Rate (z. B. 3 Token pro Sekunde), und jeder Aufruf verbraucht ein Token. Ist der Bucket leer, wird der Aufruf zurückgestellt. Für die meisten Programmiersprachen gibt es Bibliotheken, mit denen sich dies in wenigen Zeilen Code umsetzen lässt.

3. Die CPS-Grenze gilt nur für ausgehende Anrufe – jedoch für alle Endpunkt-Typen. Eingehende Anrufe unterliegen nicht der CPS-Begrenzung. Die Begrenzung für ausgehende Anrufe gilt jedoch einheitlich, unabhängig davon, welcher Endgerätetyp angerufen wird. Alle folgenden Anrufe werden auf Ihr CPS-Kontingent angerechnet:

   • phone — ausgehender Anruf an eine Festnetznummer
   • sip — Anruf an eine SIP-URI oder einen SIP-Trunk
   • websocket — Jede ausgehende WebSocket-Verbindung, die als Verbindungsabschnitt aufgebaut wird, zählt als ein Anruf im Rahmen von CPS
   • app — Aufruf eines Client SDK-/WebRTC-Endpunkts innerhalb der App

   If your application combines endpoint types within the same second – for example, when making a phone call and establishing a WebSocket connection at the same time –, both processes are counted. Set your throttling to capture the combined outgoing rate across all endpoint types, not per type.

4. Bei Wiederholungsversuchen Jitter hinzufügen. Wenn Sie einen erneuten Versuch unternehmen (z. B. bei vorübergehenden Netzwerkfehlern), fügen Sie dem Backoff einen zufälligen Jitter (50–500 ms) hinzu. Synchronisierte Wiederholungsversuche aus einem Pool von Workern können den ursprünglichen Burst nachbilden.

5. 429/503-Antworten überwachen und Warnmeldungen ausgeben. Verfolgen Sie die Ablehnungsraten in Ihrer Protokollierungspipeline. Ein plötzlicher Anstieg deutet darauf hin, dass der vorgelagerte Datenverkehr stark ansteigt. Untersuchen Sie die Ursache, bevor Sie eine Erhöhung des CPS-Limits beantragen. Um den CPS-Verbrauch in Echtzeit zum Zeitpunkt der Anruferstellung zu überwachen, verwenden Sie die return_cps_on_started Parameter in Ihrer POST /calls Anfrage oder returnCpsOnStarted in einem NCCO connect Aktion. Siehe die Referenz zum Voice API-Webhook für Einzelheiten.

SIP Trunking: CPS-Konfiguration auf der Telefonanlagen-Seite

Bei der Nutzung von Vonage SIP Trunking ist Ihre Telefonanlage der Absender der ausgehenden SIP-INVITE-Nachrichten. Die CPS-Begrenzung muss an der Telefonanlage durchgesetzt werden, bevor die Anrufe das Vonage-SIP-Gateway erreichen. Die meisten Telefonanlagen für Unternehmen verfügen über eine integrierte Funktion zur Drosselung ausgehender Anrufe oder zur Steuerung der Anrufreate in Trunk-Gruppen.

Asterisk / FreePBX

In Asterisk wird die Drosselung der ausgehenden Anrufrate auf Dialplan-Ebene mithilfe der GROUP_COUNT(${EPOCH}) Ein Mechanismus, der die innerhalb der aktuellen Sekunde initiierten Anrufe zählt und überschüssige Anrufe in einer Warteschleife hält:

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

Die call-limit Die Option an einem PJSIP-Endpunkt regelt die maximale Anzahl gleichzeitiger Kanäle, nicht die Übertragungsrate. Sie dient als Obergrenze, nicht jedoch zur Steuerung der CPS.

Weitere Informationen finden Sie unter Asterisk-Konfiguration für res_pjsip.

3CX

In 3CX kann CPS mithilfe der Gleichzeitige Anrufe Einstellung unter Admin > Sprache & Chat > [Trunk] > Registerkarte „Optionen“, wodurch die Gesamtzahl der gleichzeitigen Anrufe über die Amtsleitung (eingehende und ausgehende Anrufe zusammen) begrenzt wird. Eine konservative Einstellung dieses Werts im Verhältnis zu Ihrem Vonage-CPS-Limit bietet einen praktischen Schutz vor Anrufspitzen. Beachten Sie, dass hiermit die Kapazität für gleichzeitige Anrufe geregelt wird, nicht die Anrufaufbau-Rate.

Weitere Informationen finden Sie unter 3CX SIP Trunking-Optionen.

Cisco Unified Communications Manager (CUCM)

In einer Cisco-Umgebung wird die CPS-Drosselung vom Cisco Unified Border Element (CUBE) übernommen, dem Session Border Controller, der zwischen CUCM und dem Vonage-SIP-Gateway angesiedelt ist. Verwenden Sie auf dem CUBE den Befehl call-spike threshold und voice service voip Ratenbegrenzungsanweisungen zur Durchsetzung von CPS. Innerhalb von CUCM sorgen Standorte für eine Anrufzulassungssteuerung auf Basis der Bandbreite, die die gleichzeitige Kapazität regelt.

Weitere Informationen finden Sie unter Cisco CUBE-Konfigurationshandbuch.

Avaya Aura / Session Manager

In Avaya-Umgebungen wird die Durchsetzung der CPS vom Avaya Session Border Controller for Enterprise (SBCE) übernommen, der Richtlinien zur Signalisierungsrate pro Trunk unterstützt. Der Avaya Session Manager steuert das Anrufaufkommen über Standorte und SIP-Entity-Links, die die gleichzeitige Kapazität pro Verbindung regeln.

Weitere Informationen finden Sie unter Avaya SBCE-Dokumentation.

FreeSWITCH

FreeSWITCH erzwingt eine globale Begrenzung der Rate für neue Sitzungen über die sessions-per-second Parameter in autoload_configs/switch.conf.xml. Damit wird die Rate aller neuen Verbindungsabschnitte systemweit begrenzt:

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

Für die CPS-Steuerung pro Gateway verwenden Sie die dialplan limit Application zur Durchsetzung von Ratenbegrenzungen für eine bestimmte Gateway-Ressource.

Weitere Informationen finden Sie unter FreeSWITCH-SBC-Einrichtung/Anrufzulassungssteuerung.

Voice API: Drosselung ausgehender Anrufe

Beim Tätigen von ausgehenden Anrufen über die Voice API steuert Ihre Anwendung direkt die Rate der POST /calls Anfragen. Die Plattform gibt HTTP-Antworten zurück 429 Wenn Sie Ihr CPS-Limit bei der ersten POST /calls Anfrage. Nachfolgende Aufrufe, die über „connect“-Aktionen im NCCO initiiert werden, werden jedoch asynchron verarbeitet – sollten diese das CPS-Limit überschreiten, wird kein 429 an die ursprüngliche Anfrage zurückgegeben. Stattdessen wird ein rejected Der Status-Callback wird an Ihre Ereignis-URL mit dem detail Feld gesetzt auf 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"
}

Implementierung einer einfachen Token-Bucket-Drosselung

Das folgende Beispiel zeigt, wie man eine Reihe von ausgehenden Anrufen unter Einhaltung des CPS-Limits versendet. Es verwendet ein einfaches „Leaky-Bucket“-Muster mit asyncio (Python), das repräsentativ für die in jeder Sprache erforderliche Logik ist.

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

Wichtige Punkte

• interval = 1.0 / CPS_LIMIT Stellt bei 3 CPS genau einen Aufruf-Slot pro ~333 ms sicher. Passen Sie den Wert an, wenn Ihr Limit erhöht wird.
• Jitter verhindert, dass alle Worker in einer Multi-Prozess-Bereitstellung genau an derselben Millisekundengrenze ausgelöst werden.
• asyncio.gather ermöglicht es, dass alle Aufrufe nach ihrer Auslösung gleichzeitig ausgeführt werden können – die Begrenzung gilt nur für die Auslösungsrate, nicht für die Dauer.
• Bei Mehrprozess- oder verteilten Systemen muss der Token-Bucket gemeinsam genutzt werden (z. B. über Redis mit einem Lua-Skript oder einem dedizierten Rate-Limit-Sidecar). Ein prozessspezifischer Bucket führt dazu, dass Ihr Account-Limit überschritten wird, wenn Sie mehrere Worker ausführen.

Bearbeitung von 429 Antworten

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

Verwenden Sie einen exponentiellen Backoff mit Jitter (keine feste Wartezeit), um synchronisierte Wiederholungsstürme zwischen den Workern zu vermeiden.

Accounts with Subaccounts: Hierarchische CPS-Durchsetzung

Dieser Abschnitt ist nur relevant, wenn Sie Vonage-Subaccounts (Unter-API-Schlüssel) verwenden. Wenn Ihre Integration einen einzigen Haupt-API-Schlüssel verwendet, können Sie diesen Abschnitt überspringen. Siehe den Übersicht über die Subaccounts-API für die allgemeine Verwaltung von Subaccounts.

So funktioniert das Zweischichtenmodell

CPS wird gleichzeitig auf zwei Ebenen umgesetzt:

1. Limit für Unterkonten: Jeder einzelne Unter-API-Schlüssel verfügt über eine eigene CPS-Obergrenze. Der von diesem Schlüssel ausgehende Datenverkehr darf diese Obergrenze nicht überschreiten.
2. Obergrenze für den Haupt-API-Schlüssel: Die Gesamt-CPS aller Schlüssel (Hauptschlüssel + alle Unterkonten) unterliegt der CPS-Einstellung des Haupt-API-Schlüssels. Dies ist eine feste Obergrenze für den gesamten Account-Durchsatz.

Beide Limits gelten gleichzeitig. Ein Aufruf wird abgelehnt, sobald entweder das Unterkonto-Limit oder die Hauptschlüssel-Obergrenze erreicht ist.

Beispiel

In jeder Sekunde kann Subschlüssel 1 höchstens 10 Aufrufe auslösen, Subschlüssel 2 höchstens 10 Aufrufe und Subschlüssel 3 höchstens 10 Aufrufe; die Gesamtsumme aller drei Subschlüssel (zuzüglich etwaiger Aufrufe des Hauptschlüssels selbst) darf jedoch 20 CPS nicht überschreiten. Die Summe der Account-Limits (30) spielt keine Rolle – die Hauptobergrenze hat immer Vorrang.

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

Was das in der Praxis bedeutet

Subaccounts teilen sich das Budget des übergeordneten Kontos. Wenn Sie mehrere Workloads oder Kunden auf separaten Unterschlüsseln betreiben, konkurrieren diese um dasselbe Kontingent des Hauptschlüssels. Ein Traffic-Anstieg auf einem Subaccount kann zu Ablehnungen auf allen anderen führen, selbst wenn jedes einzelne Subaccount innerhalb seines eigenen Limits bleibt.

Sowohl SIP Trunking- als auch VAPI-Anrufe werden auf dasselbe kombinierte Limit angerechnet. Eine Mischung aus SIP INVITE Nachrichten und POST /calls Alle REST-Anfragen greifen auf denselben Hauptschlüssel-Puffer zurück. Wenn Sie beide Produkte unter derselben Account-Hierarchie nutzen, sollten Sie Ihre Kapazität entsprechend planen.

Das Limit des Hauptschlüssels ist die entscheidende Zahl. Wenn Sie eine Erhöhung des CPS beantragen, stellen Sie sicher, dass Sie das Limit des Haupt-API-Schlüssels erhöhen (die Erhöhung des Limits eines Unteraccounts bei unverändertem Hauptlimit hat keine Auswirkungen, wenn das Hauptlimit bereits die bindende Einschränkung darstellt).

Entwurf für das CPS-Subkonto

• Legen Sie die Obergrenze des Hauptkontos so fest, dass sie der maximalen Gesamtnachfrage entspricht, und nicht der Summe der Limits der Unterkonten. Wenn es selten vorkommt, dass alle Unterkonten gleichzeitig ihre Limits erreichen, ist eine Obergrenze des Hauptkontos, die unter der Summe der Unterkontolimits liegt, in Ordnung; Sie sollten jedoch das Worst-Case-Szenario berücksichtigen.
• Legen Sie die Limits für Unterkonten bewusst fest. Passen Sie die individuellen Limits der Unterkonten proportional zum erwarteten Datenverkehrsanteil der jeweiligen Workloads an. Überdimensionierte Limits für Unterkonten vermitteln ein falsches Gefühl von Spielraum.
• Wenden Sie die Drosselung pro Unteraccount im Code an, nicht nur auf der Ebene des Hauptschlüssels. Selbst wenn das Hauptkontingent großzügig bemessen ist, kann ein nicht gedrosseltes Unteraccount andere ausbremsen, indem es einen unverhältnismäßig großen Anteil beansprucht.

Beantragung einer höheren CPS-Obergrenze

Die standardmäßige Obergrenze von 3 CPS reicht für die meisten Anwendungsfälle in der Entwicklung und bei der Produktion in kleinen Stückzahlen aus. Für ausgehende Kampagnen mit hohem Volumen, Contact-Center-Bereitstellungen oder SIP-Trunks, die große PBX-Anlagen versorgen, steht eine höhere Obergrenze zur Verfügung. Kontaktieren Sie Vonage unter Berücksichtigung Ihres Anwendungsfalls und des erwarteten Anrufvolumens. Vonage wird die Anfrage prüfen und eine Erhöhung des Limits für Ihren Account vornehmen, die in der Regel innerhalb eines Werktags wirksam wird.

Weitere Lektüre

• Voice API: Einen ausgehenden Anruf tätigen
• Erste Schritte mit SIP Trunking
• API-Ratenbegrenzungen