Ratenbegrenzung in der Graph API

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. Wenn du diese Begrenzungen erreichst, erhält deine App den Fehlercode 4.

Ratenbegrenzungs-Dashboard

Im App-Dashboard deiner App kannst du die Diagramme zur Ratenbegrenzungs-Aktivität deiner App anzeigen.

Begrenzungen

Ratenbegrenzungen sind für jede App vorgegeben. Mithilfe des Ratenbegrenzungs-Tools erhältst du Informationen, wie weit deine App noch von einem möglichen Throttling entfernt ist. Klicke auf ein Beispiel, um weitere Details zu den Nutzungsvarianten zu erhalten.

Deine App kannst pro Stunde und pro Nutzer zusammengefasst 200 Aufrufe ausführen. Wenn deine App beispielsweise 100 Nutzer hat, bedeutet dies, dass du 20.000 Aufrufe ausführen kannst. Diese Begrenzung gilt nicht pro Nutzer. Es könnte also ein Nutzer 19.000 dieser Aufrufe tätigen und ein anderer 1.000. Diese Begrenzung wird basierend darauf berechnet, wie viele Aufrufe in der vorherigen Stunde getätigt wurden.

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

Die Anzahl der Nutzer für deine App wird als die durchschnittliche Anzahl täglich aktiver Nutzer zuzüglich der neuen Anmeldungen des aktuellen Tages als Schätzwert berechnet. Apps mit einer größeren Nutzeranzahl haben möglicherweise eine genauere Ratenbegrenzung als Apps mit weniger Nutzern. Apps mit sehr wenigen Nutzern haben 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. Diese Begrenzungen werden nur sehr selten erreicht. Diese Informationen werden im Detailfenster zu den einzelnen Beispielen angegeben. 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 unter https://developers.facebook.com/docs/marketing-api/api-rate-limiting.

Empfehlungen

Mit der Ratenbegrenzung wird festgelegt, wie viele API-Aufrufe innerhalb eines definierten Zeitraums ausgeführt werden können. Wenn eine Ratenbegrenzung überschritten wird, werden alle API-Aufrufe von einer App gedrosselt und schlagen für einen kurzen Zeitraum fehl. Sobald eine App gedrosselt wurde, erhält der Aufrufer für die nachfolgenden Aufrufe einen Fehler mit error code = 4, CodedException. Es kann bis zu einer Stunde dauern, bis wieder Anfragen 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 deine App genug Aufrufe tätigt, um für die Ratenbegrenzung in unserem System in Frage zu kommen, geben wir einen X-App-Usage-HTTP-Header zurück. Dieser Header enthält den aktuellen Nutzungsprozentsatz für deine App. Dieser Prozentsatz entspricht dem Wert im Ratenbegrenzungsdiagramm. 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?

Deine App überschreitet 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 Scraping-Bedingungen durchlesen.