Ratenbegrenzung in der Graph API

Mit der Ratenbegrenzung wird festgelegt, wie viele API-Aufrufe innerhalb eines definierten Zeitraums ausgeführt werden können. Ratenbegrenzungen sind für jede App vorgegeben.

Apps, die ihre Ratenbegrenzungen zu weit oder zu häufig überschreiten, können deaktiviert werden.

Die Ratenbegrenzung findet in der Facebook Graph API nur sehr selten statt. In diesem Thema wird beschrieben, wie diese Begrenzungen lauten und wie du mit ihnen umgehst.

Es gibt zwei Hauptarten von Ratenbegrenzungen für deine App: Ratenbegrenzung auf App-Ebene und Ratenbegrenzung auf Seitenebene.

Ratenbegrenzung auf App-Ebene

Diese Begrenzungen gelten für Aufrufe, die mit anderen Zugriffsschlüsseln als Seitenzugriffsschlüssel getätigt werden.

Alle API-Aufrufe, die von einer App getätigt werden, nachdem die Ratenbegrenzung überschritten wurde, werden gedrosselt und schlagen mit error code = 4, CodedException fehl. Aufrufe sind dann wieder erfolgreich, wenn die Nutzung innerhalb der letzten Stunde wieder unter die Begrenzung fällt. Begrenzungen werden basierend auf einem fortlaufenden Fenster von einer Stunde berechnet. Die aktuelle prozentuale Auslastung kannst du in deinem App-Dashboard einsehen.

Ratenbegrenzungs-Dashboard

Mithilfe des Ratenbegrenzungs-Tools erhältst du Informationen, wie weit deine App noch von einem möglichen Throttling entfernt ist. Informationen zu den Ratenbegrenzungen, die sich auf deine Apps auswirken, kannst du mithilfe von zwei Diagrammen im App-Dashboard anzeigen.

  • In einem Diagramm wird die aktuelle Auslastung angezeigt, die sich auf deine zurückgegebenen Graph API-Antworten auswirkt. Dies ist eine visuelle Darstellung des Header-Werts, der bei Graph API-Antworten zurückgegeben wird.
Diagramm für eine App, die die Ratenbegrenzung bald erreicht
  • Im zweiten Diagramm werden vergangene Ratenbegrenzungen angezeigt. Du kannst die Daten für die letzten 24 Stunden oder die letzten 7 Tage anzeigen. Du kannst auf einen beliebigen Punkt im historischen Diagramm klicken, um weitere Informationen zur Auslastung anzuzeigen, beispielsweise eine Aufschlüsselung pro Methode. Nicht für alle Apps sind historische Daten verfügbar, da das Vorhandensein dieser Daten vom Aufrufvolumen abhängt. Für Apps mit einem größeren Volumen an Aufrufen sind historische Daten mit höherer Wahrscheinlichkeit verfügbar.
Historisches Diagramm für eine App, die die Ratenbegrenzungen innerhalb der letzten 24 Stunden überschritten hat

Begrenzungen

Die Gesamtanzahl an Aufrufen, die deine App pro Stunde tätigen kann, beträgt das 200-Fache der Anzahl an Nutzern. Diese Begrenzung gilt nicht pro Nutzer. Jeder einzelne Nutzer kann mehr als 200 Aufrufe pro Stunde tätigen, solange die Gesamtanzahl aller Nutzer nicht das Maximum der App übersteigt. Wenn deine App beispielsweise 100 Nutzer hat, kann deine App 20.000 Aufrufe pro Stunde tätigen. Die zehn aktivsten Nutzer könnten jedoch 19.000 dieser Aufrufe tätigen.

Wenn für deine App eine Ratenbegrenzung gilt, sind alle Aufrufe für diese App gedrosselt – nicht nur die Aufrufe für einen bestimmten Nutzer.

Die Anzahl der Nutzer für deine App wird anhand der Anzahl täglich aktiver Nutzer und der neuen Anmeldungen des aktuellen Tages berechnet. Bei geringer täglicher Auslastung wird die Anzahl der Nutzer deiner App anhand der wöchentlich oder sogar monatlich aktiven Nutzer berechnet. Apps mit viel täglicher Interaktion haben höhere Ratenbegrenzungen als Apps mit wenig täglicher Interaktion, unabhängig von der tatsächlichen Anzahl an App-Installationen.

Warnungen:

  • Nicht alle API-Aufrufe unterliegen Ratenbegrenzungen. Die Anzahl der von dir getätigten Aufrufe stimmt also möglicherweise nicht mit der im Ratenbegrenzungs-Tool angezeigten Anzahl überein.
  • Wir drosseln Aufrufe auch auf der Grundlage der benötigten CPU-Zeit und der Gesamtzeit. Bei Endpunkten mit hohem Verarbeitungsbedarf erreicht deine App diese Begrenzungen möglicherweise auch dann, wenn die maximal möglichen Aufrufe nicht getätigt werden. Apps erreichen die Begrenzungen für CPU-Zeit und Gesamtzeit selten, außer bei speziellen Endpunkten. Informationen zu den Endpunkten, die viel CPU-Zeit oder Gesamtzeit benötigen, findest du im historischen Diagramm, sofern verfügbar.
  • In der Ads Insights API und der Marketing API werden möglicherweise andere Ratenbegrenzungen genutzt. Einzelheiten zur Marketing API findest du in der Dokumentation zur Ratenbegrenzung in der Marketing API unter https://developers.facebook.com/docs/marketing-api/api-rate-limiting.

Empfehlungen

Um eine Ratenbegrenzung zu vermeiden, empfehlen wir Folgendes:

  • 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.
  • Verwende den Ratenbegrenzungs-Header, um dein Aufrufvolumen dynamisch auszugleichen.

Ratenbegrenzungs-Header

Alle Antworten auf Aufrufe an die Graph API beinhalten einen X-App-Usage-HTTP-Header. Dieser Header enthält den aktuellen Nutzungsprozentsatz für deine App. Dieser Prozentsatz entspricht dem Wert in den Ratenbegrenzungsdiagrammen. Anhand dieser Zahl kannst du deine Aufruflast dynamisch ausgleichen, um Throttling zu vermeiden.

Der Ratenbegrenzungs-Header ist ein JSON-String mit folgendem Format:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

Die Werte für x, y und z sind Ganzzahlen, die für die Nutzungsprozentwerte für die einzelnen Kennzahlen stehen. Wenn eine dieser Kennzahlen 100 überschreitet, tritt die Ratenbegrenzung in Kraft.

Ratenbegrenzung auf Seitenebene

Diese Begrenzungen gelten für Aufrufe, die mit einem Seitenzugriffsschlüssel getätigt werden. Wenn du diese Begrenzungen erreichst, erhält deine App den Fehlercode 32.

Im Blog-Post unter https://developers.facebook.com/blog/post/2016/06/16/page-level-rate-limits/ wird die Ratenbegrenzung auf Seitenebene ausführlich erläutert.

Ratenbegrenzungs-Dashboard

Du kannst für jede Seite, mit deren Zugriffsschlüssel deine App Aufrufe tätigt, die Ratenbegrenzungsdiagramme anzeigen.

Begrenzungen

Ratenbegrenzungen werden für die einzelnen Seiten und nicht für die App auferlegt. Im Ratenbegrenzungs-Tool erhältst du Informationen dazu, wie viele Apps den Zugriffsschlüssel dieser Seite verwenden und wie nahe die Seite am Throttling liegt. Klicke auf ein Beispiel, um weitere Details zu den Nutzungsvarianten zu erhalten.

Die Anzahl der täglich aktiven Nutzer einer Seite ist die Anzahl einzelner Personen, die in einem 24-Stunden-Zeitraum mit der Seite interagiert haben. Eine Interaktion mit einer Seite besteht aus einem Klick auf die Seite oder den Seiteninhalt.

Anhand der Anzahl aktiver Nutzer in den letzten 24 Stunden werden die Ratenbegrenzungen für das aktuelle 24-Stunden-Fenster berechnet.

In einem Zeitraum von 24 Stunden können insgesamt 4.800 Aufrufe pro täglich aktivem Nutzer im Namen der Seite getätigt werden. Wenn die Seite beispielsweise 100 täglich aktive Nutzer hat, können in einem Zeitraum von 24 Stunden 480.000 Aufrufe im Namen der Seite getätigt werden. Dieser 24-Stunden-Zeitraum ist ein rollendes Fenster, das alle paar Minuten aktualisiert wird. Diese Begrenzung gilt pro Seite. Es könnte also eine App 400.000 Aufrufe tätigen und eine andere 80.000. Wenn die Ratenbegrenzung für eine Seite gilt, werden nur die Aufrufe von deiner App begrenzt, die den Zugriffsschlüssel dieser Seite verwenden. Das bedeutet, dass deine App für andere Aufrufe weiterhin ganz normal funktioniert.

Die Anzahl der Aufrufe für deine Seite wird als Schätzwert der Aufrufe berechnet, die täglich deinen Seitenzugriffsschlüssel nutzen. Seiten mit einer größeren Anzahl von Aufrufen haben möglicherweise eine genauere Ratenbegrenzung als Seiten mit weniger Aufrufen pro Tag. Seiten mit sehr wenigen Aufrufen pro Tag haben eventuell Probleme mit der Ratenbegrenzung.

Warnungen:

  • Nicht alle API-Aufrufe unterliegen Ratenbegrenzungen. Die Anzahl der von dir getätigten Aufrufe stimmt also möglicherweise nicht mit der im Ratenbegrenzungs-Tool angezeigten Anzahl überein.
  • Facebook drosselt Aufrufe auch auf der Grundlage der benötigten CPU-Zeit und der Gesamtzeit. Klicke auf das Diagramm im Ratenbegrenzungs-Tool im Dashboard, um Details hierzu anzuzeigen.
  • In der Ads Insights API und der Marketing API werden möglicherweise andere Ratenbegrenzungen genutzt. Einzelheiten zur Marketing API findest du in der Dokumentation zur Ratenbegrenzung in der Marketing API.

Empfehlungen

Sobald eine Seite gedrosselt wurde, erhält der Aufrufer für die nachfolgenden Aufrufe einen Fehler mit error code = 32, CodedException. Es kann bis zu einer Stunde dauern, bis wieder Anfragen an diese Seite akzeptiert werden.

Um eine Ratenbegrenzung zu vermeiden, empfehlen wir Folgendes:

  • 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.
  • Verwende den Ratenbegrenzungs-Header, um dein Aufrufvolumen dynamisch auszugleichen.

Ratenbegrenzungs-Header

Wenn genug Aufrufe im Namen einer Seite getätigt werden, um für die Ratenbegrenzung in unserem System in Frage zu kommen, geben wir einen X-Page-Usage-HTTP-Header zurück. Dieser Header enthält den aktuellen Nutzungsprozentsatz für die Seite. Wenn du Aufrufe mit dem Zugriffsschlüssel einer Seite tätigst, erhältst du den X-Page-Usage-Wert nur für diese Seite. Dieser Prozentsatz entspricht der Nutzung, die im Ratenbegrenzungsdiagramm für diese Seite angezeigt wird. Anhand dieser Zahl kannst du deine Aufruflast dynamisch ausgleichen, um Throttling zu vermeiden.

Der Ratenbegrenzungs-Header ist ein JSON-String mit folgendem Format:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

Die Werte für x, y und z sind Ganzzahlen, die für die Nutzungsprozentwerte für die einzelnen Kennzahlen stehen. Wenn eine dieser Kennzahlen 100 überschreitet, tritt die Ratenbegrenzung in Kraft.

Ratenbegrenzung auf Kontoebene

Diese Begrenzungen gelten für Aufrufe über Benutzerzugriffsschlüssel. Deine App erhält Fehlercode 17, falls die Begrenzung erreicht ist. Dieser Fehler tritt auf, wenn ein bestimmtes Nutzerkonto zu viele Aufrufe an die API vornimmt.

Hinweis:

Dies betrifft auch Nutzeraufrufe über viele Apps – nicht nur über deine.

Wenn für den Nutzer eine Ratenbegrenzung vorliegt, werden API-Aufrufe von diesem Nutzer gedrosselt.

Um eine Ratenbegrenzung zu vermeiden, empfehlen wir Folgendes:

Es gibt keine Möglichkeit, dies zu verhindern. Der Nutzer nimmt zu viele Aufrufe vor (möglicherweise über andere Apps) und verursacht so eine Ratenbegrenzung. Wenn dies jedoch bei vielen Nutzern einer App auftritt, dann wurde dies höchstwahrscheinlich durch die API-Aufrufe über diese App verursacht. In diesem Fall solltest du die Anzahl ihrer Aufrufe verringern oder sie gleichmäßiger verteilen.

FAQ

Was gilt als API-Aufruf?

Alle Aufrufe werden in die Ratenbegrenzungen einbezogen, nicht nur einzelne HTTPS-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, auch wenn du nur eine HTTPS-API-Anfrage tätigst.

Die folgenden Beispiele veranschaulichen dies etwas:

Beispielanfragen Anzahl an API-Aufrufen

GET https://graph.facebook.com/photos?id=4
GET https://graph.facebook.com/photos?id=5
GET https://graph.facebook.com/photos?id=6

3

GET https://graph.facebook.com/photos?id=4,5,6

3

Wenn du mehrere Objekte nach ID durchlaufen musst, empfehlen wir dringend, den zweiten Ansatz zu verwenden, da er die Performance deiner API-Antworten verbessert. Er reduziert aber nicht die Anzahl der Aufrufe im Sinne der Ratenbegrenzung.

Du kannst deine Anfragen auch mit der Batch API zusammenfassen. Achte dabei aber darauf, dass jede Unteranfrage einen eigenen API-Aufruf oder sogar mehrere API-Aufrufe darstellt, wenn du mehrere IDs angibst.

Wenn die Ratenbegrenzung bei deiner App oder Seite in Kraft tritt, tragen auch API-Aufrufe, bei denen Ratenbegrenzungsfehler auftreten, zum Erreichen der Ratenbegrenzung bei.


Welche Fehler werden für meine App angezeigt?
Throttling-Typ Mindestens Fehlercode

Throttling auf App-Ebene

200 Aufrufe/Person/Stunde

4

Throttling auf Kontoebene

Nicht zutreffend

17

Throttling auf Seitenebene

4800 Aufrufe/Person/24 Stunden

32

Throttling auf benutzerdefinierter Ebene

Nicht zutreffend

613


Ich sehe Fehlercode 613. Was kann ich tun?

Wenn in deiner Fehlerantwort error_subcode 1996 enthalten ist, hat Facebook ein inkonsistentes Verhalten beim API-Anfragevolumen deiner App ermittelt. Dieser Fehler kann auftreten, wenn du kürzlich Änderungen vorgenommen hast, die sich auf die Anzahl der API-Anfragen auswirken.

Wenn der Untercode nicht angezeigt wird, überschreitet deine App eine benutzerdefinierte Ratenbegrenzung. Wende dich zur Behebung dieses Problems an deinen Partnermanager.


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

Wenn du einen Dienst erstellst, der Daten ausliest, solltest du dir unsere Nutzungsbedingungen für Scraping durchlesen.