Durchsatzratenbegrenzungen

Eine Ratenbegrenzung ist die Anzahl an API-Aufrufen, die von einer App oder einem*einer Nutzer*in innerhalb eines bestimmten Zeitraums getätigt werden können. Wird diese Begrenzung überschritten oder werden die Beschränkungen im Hinblick auf CPU-Zeit oder Gesamtzeit überschritten, wird die App oder der*die Nutzer*in möglicherweise gedrosselt. Ist dies der Fall, schlagen die Anfragen der App oder des*der Nutzer*in fehl.

Alle API-Anfragen unterliegen Durchsatzratenbegrenzungen. Graph API- und Instagram Basic Display API-Anfragen unterliegen Plattform-Durchsatzratenbegrenzungen, während Marketing API- und Instagram-Plattform-Anfragen Business Use Case (BUC)-Durchsatzratenbegrenzungen unterliegen.

Pages API-Anfragen unterliegen Plattform- oder BUC-Durchsatzratenbegrenzungen, je nachdem, welches Token in der Anfrage verwendet wurde. Mit App- oder Nutzer*innen-Zugriffstoken getätigte Anfragen unterliegen Plattform-Durchsatzratenbegrenzungen, während mit Systemnutzer*innen- oder Seiten-Zugriffstoken getätigte Anfragen BUC-Durchsatzratenbegrenzungen unterliegen.

Nutzungsstatistiken für Ratenbegrenzungen in Echtzeit werden in Headern beschrieben, die in den meisten API-Antworten enthalten sind, sobald genügend Aufrufe für einen Endpunkt getätigt wurden. Nutzungsstatistiken für Plattform-Ratenbegrenzungen werden auch im App-Dashboard angezeigt. Sobald eine Ratenbegrenzung erreicht wird, schlagen alle nachfolgend von deiner App getätigten Anfragen fehl und die App gibt einen Fehler aus, bis ausreichend Zeit verstrichen ist und die Aufrufanzahl wieder unter den Grenzwert sinkt.

Können für eine Anfrage Plattform- und BUC-Ratenbegrenzungen angewendet werden, finden die BUC-Ratenbegrenzungen Anwendung.

Plattform-Ratenbegrenzungen

Plattform-Ratenbegrenzungen werden für eine einzelne App oder auf Nutzungsebene nachverfolgt, je nachdem, welche Art Token in der Anfrage verwendet wurde.

Anwendungen

Mit einem App-Zugriffsschlüssel getätigte Graph API-Anfragen werden auf die Ratenbegrenzung der App angerechnet. Die Anzahl der Aufrufe einer App ist die Anzahl der Aufrufe, die die App während eines rollierenden Zeitfensters von einer Stunde durchführen kann. Sie wird wie folgt berechnet:

Die Anzahl der Nutzer*innen basiert auf der Anzahl der individuellen täglichen aktiven Nutzer*innen einer App. In Fällen, in denen starke Schwankungen der täglichen Nutzung zu beobachten sind, wie zum Beispiel bei einer App, die an Wochentagen eine geringe Aktivität verzeichnet, wird die Zahl der Nutzer*innen für deine App anhand der wöchentlich und monatlich aktiven Nutzer*innen berechnet. Apps mit einer hohen täglichen Interaktion haben höhere Ratenbegrenzungen als Apps mit geringer täglicher Interaktion. Dies gilt unabhängig von der tatsächlichen Zahl der App-Installationen.

Beachte, dass dies keine Begrenzung pro Nutzer*in sondern eine Begrenzung der von deiner App getätigten Aufrufe ist. Die einzelnen Nutzer*innen können mit deiner App mehr als 200 Aufrufe pro Stunde vornehmen, solange die Gesamtmenge für alle Nutzer*innen die App-Obergrenze nicht überschreitet. Wenn deine App beispielsweise 100 Nutzer*innen hat, bedeutet dies, dass die App 20.000 Aufrufe pro Stunde ausführen kann. Aber die zehn aktivsten Nutzer*innen könnten 19.000 dieser Aufrufe auf sich vereinigen.

Nutzer*innen

Mit einem Nutzer-Zugriffsschlüssel getätigte Graph API-Anfragen werden auf die Anzahl Aufrufe dieses*dieser Nutzer*in angerechnet. Die Anzahl der Aufrufe eines*einer Nutzer*in ist die Anzahl der Aufrufe, die er*sie während eines rollierenden Zeitfensters von einer Stunde durchführen kann. Aus Datenschutzgründen veröffentlichen wir keine tatsächlichen Aufrufanzahlen für Nutzer*innen.

Dabei ist zu beachten, dass sich die Aufrufanzahl eines*einer Nutzer*in auf mehrere Apps verteilen kann. So kann ein*e Nutzer*in beispielsweise X Aufrufe über App1 und Y Aufrufe über App2 tätigen. Überschreitet X+Y die Aufrufanzahl eines*einer Nutzer*in, wird für diese*n Nutzer*in die Ratenbegrenzung aktiviert. Das heißt nicht notwendigerweise, dass eine App etwas falsch macht. Möglicherweise verwendet der*die Nutzer*in mehrere Apps oder verwendet die API falsch.

Header

Endpunkte, die ausreichend Anfragen von deiner App erhalten, beinhalten in ihren Antworten einen X-App-Usage- oder X-Ad-Account-Usage-HTTP-Header (für Apps mit v3.3 oder älter). Der Header enthält einen String im JSON-Format, der die aktuelle Nutzung der App-Ratenbegrenzung beschreibt.

Header-Inhalt

X-Ad-Account-Usage Header-Inhalte

CPU-Zeit gesamt

Die für die Verarbeitung der Anfrage benötigte CPU-Zeit. Wenn total_cputime gleich 100 ist, werden Aufrufe möglicherweise gedrosselt.

Zeit gesamt

Die für die Verarbeitung der Anfrage benötigte Zeit. Wenn total_time gleich 100 ist, werden Aufrufe möglicherweise gedrosselt.

Beispiel X-App-Usage Header-Wert

x-app-usage: {
    "call_count": 28,         //Percentage of calls made 
    "total_time": 25,         //Percentage of total time
    "total_cputime": 25       //Percentage of total CPU time
}

Beispiel X-Werbekontonutzung Header-Wert

x-ad-account-usage: {
    "acc_id_util_pct": 9.67,   //Percentage of calls made for this ad account.
    "reset_time_duration": 100,   //Time duration (in seconds) it takes to reset the current rate limit score.
    "ads_api_access_tier": 'standard_access'   //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
}

Dashboard

Im App-Dashboard werden die Anzahl der Nutzer*innen mit Ratenbegrenzungen, der aktuelle Prozentsatz der Nutzung der App-Ratenbegrenzungen und die durchschnittliche Aktivität in den letzten 7 Tagen angezeigt. Klicke in der Karte App-Ratenbegrenzung auf Details anzeigen und zeige auf einen beliebigen Punkt der Grafik, um weitere Details zur Nutzung in diesem konkreten Moment aufzurufen. Da die Nutzung vom Aufkommen der Aufrufe abhängt, werden in dieser Grafik eventuell nicht volle 7 Tage angezeigt. Bei Apps mit einem höheren Aufrufaufkommen werden mehr Tage angezeigt.

Fehlercodes

Ist für eine App oder eine*n Nutzer*in die Ratenbegrenzung erreicht, werden von dieser App oder diesem*dieser Nutzer*in getätigte Anfragen gefüllt und die API antwortet mit einem Fehlercode.

Throttling-Fehlercodes

Beispielantwort

{
  "error": {
    "message": "(#32) Page request limit reached",
    "type": "OAuthException",
    "code": 32,
    "fbtrace_id": "Fz54k3GZrio"
  }
}

Stabilitäts-Drosselungscodes von Facebook

Best Practices

• Wenn der Grenzwert erreicht ist, solltest du keine API-Aufrufe mehr vornehmen. Bei weiteren Aufrufen wird die Aufrufanzahl weiter erhöht und es dauert noch länger, bis Aufrufe wieder erfolgreich sind.
• Verteile Anfragen gleichmäßig, um Traffic-Spitzen zu vermeiden.
• Verwende Filter, um die Datenantwortgröße zu begrenzen und Aufrufe zu vermeiden, die überlappende Daten anfordern.
• Sieh im X-App-Usage-HTTP-Header nach, wie weit deine App von diesem Grenzwert entfernt ist und wann du wieder Aufrufe tätigen kannst, nachdem der Grenzwert erreicht wurde.
• Werden Nutzer*innen gedrosselt, stelle sicher, dass dies nicht von deiner App verursacht wurde. Reduziere die Anzahl der Aufrufe des*der Nutzer*in oder verteile die Aufrufe des*der Nutzer*in gleichmäßiger.

Business Use Case-Ratenbegrenzungen

Alle von einem System- oder Seiten-Zugriffsschlüssel getätigten Marketing API- und Pages API-Aufrufe unterliegen Business Use Case (BUC)-Ratenbegrenzungen und sind von den Endpunkten abhängig, die du abfragst.

Für die Marketing-API wird die Ratenbegrenzung auf das Werbekonto für denselben Business-Anwendungsfall angewendet. So nutzen zum Beispiel alle Endpunkte mit dem Business-Anwendungsfall Werbeanzeigenmanagement eine Gesamtquote innerhalb eines Werbekontos. Tätigt ein bestimmter Endpunkt viele API-Anfragen und verursacht dadurch Throttling, erhalten andere Endpunkte, die mit demselben Business-Anwendungsfall konfiguriert sind, ebenfalls Ratenbegrenzungsfehler. Die Quote hängt von der Access Tier der Marketing API der App ab. Die Standard-Zugriff-Tier der Marketing-API verfügt über mehr Quoten als der Entwicklungs-Zugriff-Tier der Marketing-API. Standardmäßig sollte eine neue App auf der Entwicklungs-Tier sein. Wenn du ein Upgrade durchführen musst, um eine höhere Ratenbegrenzungsquote zu erhalten, führst du ein Upgrade auf Erweiterten Zugriff für Standardzugriff für Anzeigenmanagement in der App Review durch.

Ads Insights

Anfragen, die von deiner App an die Ads Insights API gesendet werden, werden auf die Ratenbegrenzungs-Kennzahlen der App, wie zum Beispiel Anzahl Anrufe, Gesamt-CPU-Zeit und Gesamtzeit angerechnet. Die Anzahl der Aufrufe einer App ist die Anzahl der Aufrufe, die sie während eines rollierenden Zeitfensters von einer Stunde durchführen kann.

Für Apps mit Standardzugriff auf die Standardzugriff-Funktion des Anzeigenmanagements:

Für Apps mit erweitertem Zugriff auf die Standardzugriff-Funktion des Anzeigenmanagements:

Die „Number of Active ads“ ist die Anzahl der aktiven Werbeanzeigen für jedes Werbekonto. Nutzerfehler gibt die Anzahl der Fehler an, die am Aufruf der API erhalten wurden. Um eine höhere Ratenbegrenzung zu erhalten, kannst du das Feature Standardzugriff für das Anzeigenmanagement anfordern.

Die Ratenbegrenzung unterliegt möglicherweise auch der Gesamt-CPU-Zeit und der Gesamt-Wand-Zeit während des laufenden einstündigen Zeitfensters. Mehr Informationen findest du unter HTTP-X-Business-Use-Case-Header total_cputime und total_time.

Erhältst du einen Ratenbegrenzungsfehler, kannst du auch auf estimated_time_to_regain_access im X-Business-Use-Case-Header für die geschätzte Sperrzeit verweisen.

Verwaltung von Werbeanzeigen

Anfragen, die von Ihrer App an die Ads Management API gesendet werden, werden auf die Ratenbegrenzungs-Kennzahlen der App, wie zum Beispiel die Anzahl der Aufrufe, Gesamt-CPU-Zeit und Gesamtzeit angerechnet. Die Anzahl der Aufrufe einer App ist die Anzahl der Aufrufe, die sie während eines rollierenden Zeitfensters von einer Stunde durchführen kann.

Für Apps mit Standardzugriff auf die Standardzugriffsfunktion des Werbeanzeigenmanagements:

Für Apps mit erweitertem Zugriff auf die Standardzugriff-Funktion des Anzeigenmanagements:

Die Anzahl der aktiven Werbeanzeigen ist die Anzahl der Werbeanzeigen für jedes Werbekonto.

Die Ratenbegrenzung unterliegt möglicherweise auch der Gesamt-CPU-Zeit und der Gesamt-Wand-Zeit während des laufenden einstündigen Zeitfensters. Mehr Informationen findest du unter HTTP-X-Business-Use-Case-Header total_cputime und total_time.

Erhältst du einen Ratenbegrenzungsfehler, kannst du auch auf estimated_time_to_regain_access im X-Business-Use-Case-Header für die geschätzte Sperrzeit verweisen.

Katalog

Katalog-Batch

Aufrufe deiner App werden auf die Ratenbegrenzungs-Kennzahlen, wie Anzahl der Aufrufe, Gesamt-CPU-Zeit und Gesamtzeit angerechnet, die deine App während eines rollierenden Zeitfensters von einer Stunde für jede Katalog-ID durchführen kann. Sie werden wie folgt berechnet:

„unique users“ ist die Anzahl der individuellen Nutzer*innen eines Unternehmens (in allen Katalogen) mit Intent in den letzten 28 Tagen. Je mehr Nutzer*innen Produkte in deinen Katalogen sehen, umso höher ist die zugeteilte Aufrufquote.

Katalogverwaltung

Aufrufe deiner App werden gegen die Anzahl der Aufrufe gezählt, die sie während eines rollierenden Zeitfensters von einer Stunde je Katalog-ID durchführen kann, und wie folgt berechnet:

„Individuelle Nutzer*innen“ ist die Anzahl der individuellen Nutzer*innen eines Unternehmens (in allen Katalogen) mit Intent in den letzten 28 Tagen. Je mehr Nutzer*innen Produkte in deinen Katalogen sehen, umso höher ist die zugeteilte Aufrufquote.

Diese Formel wird auf verschiedene Katalogendpunkte angewendet.

Mehr Informationen zur Abfrage der aktuellen Ratennutzung findest du unter Header.

Die Ratenbegrenzung unterliegt möglicherweise auch der Gesamt-CPU-Zeit und der Gesamt-Wand-Zeit während des laufenden einstündigen Zeitfensters. Mehr Informationen findest du unter HTTP-X-Business-Use-Case-Header total_cputime und total_time.

Erhältst du einen Ratenbegrenzungsfehler, kannst du auch auf estimated_time_to_regain_access im X-Business-Use-Case-Header für die geschätzte Sperrzeit verweisen.

Custom Audiences

Anfragen, die von deiner App an die Custom Audience API gesendet werden, werden auf die Ratenbegrenzungs-Kennzahlen, wie die Anzahl der Aufrufe, Gesamt-CPU-Zeit und Gesamtzeit angerechnet. Die Anzahl der Aufrufe einer App ist die Anzahl der Aufrufe, die sie während eines rollierenden Zeitfensters von einer Stunde durchführen kann. Sie wird wie folgt berechnet, überschreitet jedoch nie den Wert 700.000:

Für Apps mit Standardzugriff auf die Funktion Werbeanzeigenmanagement-Standardzugriff:

Für Apps mit erweitertem Zugriff auf die Standardzugriff-Funktion des Anzeigenmanagements:

Die Anzahl der aktiven Custom Audiences ist die Anzahl der aktiven Custom Audiences für jedes Werbekonto.

Die Ratenbegrenzung unterliegt möglicherweise auch der Gesamt-CPU-Zeit und der Gesamt-Wand-Zeit während des laufenden einstündigen Zeitfensters. Mehr Informationen findest du unter HTTP-X-Business-Use-Case-Header total_cputime und total_time.

Erhältst du einen Durchsatzratenbegrenzungsfehler, kannst du auch auf estimated_time_to_regain_access im X-Business-Use-Case-Header für die geschätzte Sperrzeit verweisen.

Instagram-Plattform

LeadGen

Anfragen, die deine App an die LeadGen API sendet, werden zur Aufrufanzahl deiner App addiert. Die Anzahl der Aufrufe einer App ist die Anzahl der Aufrufe, die sie während eines rollierenden Zeitfensters von einer Stunde durchführen kann:

„Leads Generated“ ist die Anzahl der Leads, die pro Seite in den letzten 90 Tagen für dieses Werbekonto generiert wurden.

Messenger-Plattform

Seiten

Die Seiten-Ratenbegrenzungen können die Plattform- oder die BUC-Ratenbegrenzungslogik verwenden, je nachdem, welcher Schlüsseltyp verwendet wird. Alle Pages API-Aufrufe, die mit einem Seiten- oder Systemnutzer-Zugriffsschlüssel getätigt werden, verwenden die nachstehende Ratenbegrenzungsberechnung. Alle mit App- oder Nutzer-Zugriffsschlüsseln getätigten Aufrufe unterliegen den App- oder Nutzer-Ratenbegrenzungen.

Anfragen, die deine App mit einem Seiten-Zugriffsschlüssel oder einem Systemnutzer-Zugriffsschlüssel an die Pages API sendet, werden zur Aufrufanzahl deiner App addiert. Die Anzahl der Aufrufe einer App ist die Anzahl der Aufrufe, die sie während eines rollierenden Zeitfensters von einer Stunde durchführen kann:

Die „Number of Engaged Users“ ist die Anzahl der Nutzer*innen, die pro 24 Stunden mit der Seite interagiert haben.

Anfragen, die deine App mit einem Nutzer-Zugriffsschlüssel oder einem App-Zugriffsschlüssel an die Pages API sendet, folgen der Plattform-Ratenbegrenzungslogik.

Wir empfehlen dir, ein Systemnutzer-Zugriffstoken zu verwenden, um Probleme mit der Ratenbegrenzung zu vermeiden, wenn du die Funktion für den Zugriff auf öffentliche Seiteninhalte nutzt.

Spark AR Commerce Effect Management

Anfragen, die deine App an Commerce-Endpunkte sendet, werden zur Aufrufanzahl deiner App addiert. Die Anzahl der Aufrufe einer App ist die Anzahl der Aufrufe, die die App während eines rollierenden Zeitfensters von einer Stunde durchführen kann. Sie wird wie folgt berechnet:

Die „Number of Catalogs“ ist die Gesamtzahl von Katalogen in allen Commerce-Konten, die von deiner App verwaltet werden.

Threads

WhatsApp Business Management API

Header

Alle von deiner App ausgegebenen API-Antworten, für die nach der BUC-Logik eine Ratenbegrenzung gilt, beinhalten einen X-Business-Use-Case-Usage-HTTP-Header (für Ads API-Aufrufe der Versionen 3.3 und älter) mit einem String im JSON-Format, der die aktuelle Nutzung der App-Ratenbegrenzung beschreibt. Dieser Header kann bis zu 32 Objekte in einem Aufruf zurückgeben.

X-Business-Use-Case-Usage Header-Inhalt

CPU-Zeit gesamt

Die für die Verarbeitung der Anfrage benötigte CPU-Zeit. Wenn „total_cputime“ gleich 100 ist, werden Aufrufe möglicherweise gedrosselt.

Zeit gesamt

Die für die Verarbeitung der Anfrage benötigte Zeit. Wenn „total_time“ gleich 100 ist, werden Aufrufe möglicherweise gedrosselt.

Ads API-Zugriffsstufe

Nur für die Typen ads_insights und ads_management. Mit Stufen kann deine App auf die Marketing API zugreifen. Standardmäßig befinden sich Apps in der Stufe development_access. standard_access aktiviert die niedrigere Durchsatzratenbegrenzung. Um eine höhere Ratenbegrenzung zu erhalten und in die Standardstufe zu gelangen, kannst du „erweiterten Zugriff“ auf die Funktion Standardzugriff auf Ads Management anfordern.

Beispiel X-Business-Use-Case-Usage Header-Wert

x-business-use-case-usage: {
    "{business-object-id}": [
        {
            "type": "{rate-limit-type}",           //Type of BUC rate limit logic being applied.
            "call_count": 100,                     //Percentage of calls made. 
            "total_cputime": 25,                   //Percentage of the total CPU time that has been used.
            "total_time": 25,                      //Percentage of the total time that has been used.   
            "estimated_time_to_regain_access": 19,  //Time in minutes to regain access.
            "ads_api_access_tier": "standard_access"  //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
        }
    ],      
    "66782684": [
        {
            "type": "ads_management",
            "call_count": 95,
            "total_cputime": 20,
            "total_time": 20,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access" 
        }
    ],
    "10153848260347724": [
        {
            "type": "ads_insights",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access"
        }
    ],
    "10153848260347724": [
        {
            "type": "pages",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0
        }
    ],
...
}

Fehlercodes

Wenn für deine App die BUC-Ratenbegrenzung erreicht ist, schlagen später von deiner App getätigte Aufrufe fehl und die App antwortet mit einem Fehlercode.

Beispiel-Fehlercodemeldung

{   
"error": {      
    "message": "(#80001) There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.",      
    "type": "OAuthException",      
    "code": 80001,      
    "fbtrace_id": "AmFGcW_3hwDB7qFbl_QdebZ"   
    }
}

Best Practices

• Wenn der Grenzwert erreicht ist, solltest du keine API-Aufrufe mehr vornehmen. Bei weiteren Aufrufen wird die Aufrufanzahl weiter erhöht und es dauert noch länger, bis Aufrufe wieder erfolgreich sind.
• Sieh im X-Business-Use-Case-Usage-HTTP-Header nach, wie weit dein Werbekonto von diesem Grenzwert entfernt ist.
• Prüfe den Fehlercode und den API-Endpunkt, um den Throttling-Typ zu bestätigen.
• Wechsle zu anderen Werbekonten und kehre später wieder zu diesem Konto zurück.
• Du solltest eher eine neue Werbeanzeige erstellen, als vorhandene zu ändern.
• Sende Abfragen gleichmäßig zwischen zwei Zeitintervallen, damit keine Traffic-Spikes erzeugt werden.
• Verwende Filter, um die Datenantwortgröße zu begrenzen und Aufrufe zu vermeiden, die überlappende Daten anfordern.

FAQs

Was gilt als API-Aufruf?

Alle Aufrufe werden in die Ratenbegrenzungen einbezogen, nicht nur einzelne-API-Anfragen. Du kannst beispielsweise einen einzelnen API-Aufruf tätigen und mehrere IDs angeben. Dabei würde jede ID als eigener API-Aufruf erfasst werden.

Dieses Konzept wir durch die folgende Tabelle erklärt.

Wir empfehlen, nach Möglichkeit mehrere IDs in einer API-Anfrage anzugeben, da sich damit die Performance deiner API-Antworten verbessert.

Ich erstelle einen Scraper. Gibt es etwas, das ich beachten muss?

Wenn du einen Dienst erstellst, der Daten ausliest, lies dir bitte unsere Scraping-Bedingungen durch.