Metas x-app-usage-Header sind drei Prozentwerte und keine Uhr

Was ist der x-app-usage-Header?

Meta liefert den x-app-usage-Header in Graph-API-Antworten mit, um einer App zu sagen, wie viel ihres eigenen Rate Limits sie schon verbraucht hat. Die Referenz zum Rate Limiting führt ihn in einem Satz ein: „Endpoints that receive enough requests from your app will include a X-App-Usage or X-Ad-Account-Usage (for v3.3 and older Ads API calls) HTTP header in their responses. The header will contain a JSON-formatted string that describes current application rate limit usage.“

In diesem Satz verstecken sich zwei Bedingungen. Der Header gehört der App, nicht dem Konto und nicht dem Nutzer, dessen Token den Aufruf gemacht hat. Und er kommt nur an Endpunkten, die genug Traffic gesehen haben, was Meta anderswo als Header umschreibt, die „included with most API responses once enough calls have been made to an endpoint“ sind. Eine Antwort ohne x-app-usage bedeutet, dass Meta keine Auskunft gibt, nicht dass die Nutzung null ist.

Der Wert ist ein JSON-Objekt mit drei Schlüsseln und sonst nichts. Metas eigenes Beispiel:

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
}

Welche Anfragen diesen Header statt eines anderen bekommen, hängt von der API und vom Token ab. Meta trennt das sauber: „Graph API requests are subject to Platform Rate Limits, while Marketing API and Instagram Platform requests are subject to Business Use Case (BUC) Rate Limits.“ Aufrufe der Pages API landen je nach Zugangsdaten auf der einen oder der anderen Seite, mit Application- und User-Access-Token auf der Platform-Seite und System-User- oder Page-Access-Token auf der Business-Use-Case-Seite.

Was bedeuten die drei Felder in x-app-usage?

Alle drei sind Prozentwerte eines Kontingents, keine Zählwerte von irgendetwas.

Das Wort „whole“ leistet echte Arbeit. Jeder Wert in x-app-usage ist eine ganze Zahl, die feinste Auflösung, die du bekommst, ist also ein Prozent des Budgets. Metas anderer Header auf App-Ebene ist bei derselben Idee genauer: Das Feld acc_id_util_pct in X-Ad-Account-Usage taucht im Beispiel als 9.67 auf, mit Nachkommastellen. x-app-usage rundet.

Die drei Felder drosseln außerdem unabhängig voneinander. Meta hängt an beide Zeitfelder dieselben zwei Zeilen: „When total_cputime reaches 100, calls may be throttled“ und „When total_time reaches 100, calls may be throttled.“ Eine Handvoll teurer Abfragen kann total_cputime an die Decke treiben, während call_count noch einstellig ist, eine App, die nur das Aufrufvolumen beobachtet, übersieht also zwei der drei Wege, auf denen sie blockiert wird.

Beachte, was Meta dort nicht veröffentlicht. Die Referenz nennt eine Schwelle für total_cputime und eine für total_time und schreibt den passenden Satz für call_count im Abschnitt zu den Platform-Headern nie. Stattdessen heißt es allgemein: „Once a rate limit is reached, any subsequent requests made by your app will fail and the API will return an error code until enough time has passed for the call count to drop below the limit.“ Lies die 100 bei call_count trotzdem als das Limit, denn nichts im Dokument deutet auf eine andere Zahl hin.

Woran werden die Prozentwerte gemessen?

An einer Formel auf App-Ebene, die Meta vollständig veröffentlicht: Calls within one hour = 200 * Number of Users.

Der Faktor liegt fest, der zweite Wert ist Engagement. Meta definiert ihn als „the number of unique daily active users an app has“, mit einem Rückfallweg für ungleichmäßigen Traffic: „In cases where there are slow periods of daily usage, such as if your app has high activity on weekends but low activity over weekdays, the weekly and monthly active Users are used to calculate the number of Users for your app.“ Installationen spielen keine Rolle. Meta sagt es direkt: Apps mit hohem täglichem Engagement bekommen höhere Grenzen „regardless of the actual number of app installs.“

Der Topf wird geteilt, nicht aufgeteilt. Meta rechnet es selbst vor: „if your app has 100 Users, your app can make 20,000 calls per hour. However, your top ten most engaged Users could make 19,000 of those calls.“ Ein einzelnes lautes Konto kann den Rest der Nutzer einer App innerhalb derselben Stunde aushungern, und nichts im Platform-Limit verhindert das.

User-Token tragen eine zweite, getrennte Zählung, die kein Header meldet. Die eigene Aufrufzahl eines Nutzers läuft auf einer eigenen gleitenden Stunde und umfasst jede App, die er benutzt, deshalb warnt Meta, dass ein Nutzer „could make X calls through App1 and Y calls through App2“ und über die Summe limitiert wird. Dann macht Meta die Tür zu: „Due to privacy concerns, we do not reveal actual call count values for users.“ Es gibt keinen x-user-usage-Header. Die Nutzerseite der Platform Rate Limits ist per Design nicht beobachtbar.

Eine Zählregel erwischt alle, die batchen. Metas FAQ hält fest, dass „each ID counts as one API call“, und zeigt es: Drei einzelne Anfragen mit je einer ID zählen als drei Aufrufe, und eine Anfrage mit ids=4,5,6 zählt ebenfalls als drei. Batching verbessert die Antwortzeit und kauft kein Kontingent. Das ist ein anderes Abrechnungsmodell als die Anfragegrenzen pro Endpunkt, die Bluesky veröffentlicht, und als die Trennung von Pinterest zwischen App- und Nutzerebene.

Wie unterscheidet sich x-app-usage vom Business-Use-Case-Header?

Anderer Geltungsbereich, andere Form, und einer der beiden sagt dir, wann du wieder reinkommst.

Der Business-Use-Case-Header ist der reichhaltigere der beiden, und er ist derjenige, auf den es bei Instagram-Publishing ankommt. Metas Formel aus 4800 mal Impressionen und die Felder in X-Business-Use-Case-Usage sind separat ausführlich beschrieben, einschließlich der type-Werte und der Fehlercodes, die an jedem hängen.

Wo sich die beiden Header berühren, widerspricht sich Metas eigenes Dokument. Der Platform-Abschnitt hängt den Einschub „(for v3.3 and older Ads API calls)“ an X-Ad-Account-Usage, was er auch beschreibt. Der Abschnitt zum Business Use Case wiederholt denselben Einschub dann an einem anderen Header: „All API responses made by your app that are rate limited using the BUC logic include an X-Business-Use-Case-Usage (for v3.3 and older Ads API calls) HTTP header.“ Der Business-Use-Case-Header ist nicht auf v3.3 und ältere Aufrufe beschränkt, und der Rest desselben Abschnitts dokumentiert ihn als den aktuellen Mechanismus für Instagram- und Marketing-API-Traffic. Behandle den Zusatz als Copy-and-paste-Rest.

Die Vorrangregel zwischen beiden ist die eine Zeile, die man sich merken sollte: „If both Platform and Business Use Case rate limits can be applied to a request, BUC rate limits will be applied.“

Was passiert, wenn x-app-usage 100 anzeigt?

Aufrufe scheitern mit einem nummerierten Fehler, und welche Nummer es ist, hängt davon ab, wessen Limit gebrochen wurde.

Metas Anweisung zu allen ist dieselbe, und sie ist keine Backoff-Regel: „When the limit has been reached, stop making API calls. Continuing to make calls will continue to increase your call count, which will increase the time before calls will be successful again.“

Das ist der Satz, den die meisten Retry-Schleifen falsch machen. Exponentielles Backoff sendet weiterhin Anfragen, und laut Meta schiebt jede davon den Zeitpunkt der Freigabe weiter hinaus. Die richtige Reaktion auf Fehlercode 4 ist, die Warteschlange anzuhalten, nicht sie zu verlangsamen.

Dann kommt die Lücke. Metas eigene Best Practice zur Erholung sagt: „Check the X-App-Usage HTTP header to see how close your app is to its limit and when you can resume making calls when the limit has been reached.“ Der Header hat drei Felder, alle davon Prozentwerte, und keines davon ist eine Zeit. estimated_time_to_regain_access gibt es am Business-Use-Case-Header. reset_time_duration gibt es an X-Ad-Account-Usage. Keines von beiden gibt es an x-app-usage. Meta sagt dir, du sollst eine Wiederaufnahmezeit aus einem Header lesen, der keine trägt.

Was du stattdessen bekommst, ist das App Dashboard, wo Meta „the app's current Application Rate Limits usage percentage“ und die durchschnittliche Aktivität der letzten sieben Tage anzeigt. Das ist ein Diagramm für Menschen, kein Feld, das deine Retry-Logik lesen kann. Praktisch beobachtest du, wie call_count klettert, hörst deutlich vor 100 auf und verteilst den Traffic gleichmäßig, was auch Metas erklärter Rat ist: „Spread out queries evenly to avoid traffic spikes.“ Veröffentlichungspläne stoßen zusätzlich auf die getrennten, unnummerierten Grenzen, und die täglichen Posting-Limits von Facebook sind ein eigenes System mit eigenem Verhalten.

Häufig gestellte Fragen

Welche drei Felder stecken im x-app-usage-Header?

call_count, total_cputime und total_time. Meta definiert jedes als ganze Zahl, die einen Prozentwert ausdrückt, von den Aufrufen über eine gleitende Stunde und von der CPU-Zeit und der Gesamtzeit, die für die Abfrageverarbeitung zugeteilt sind.

Welches Rate Limit auf App-Ebene steckt hinter call_count?

Calls within one hour = 200 * Number of Users, wobei die Zahl der Nutzer Metas Zählung der eindeutigen täglich aktiven Nutzer der App ist, mit Rückfall auf wöchentlich und monatlich Aktive, wenn der tägliche Traffic ungleichmäßig ist.

Welcher Fehlercode bedeutet, dass das x-app-usage-Limit erreicht wurde?

Fehlercode 4, den Meta „API Too Many Calls“ nennt. Code 17 deckt das Limit des Nutzers selbst ab, und Code 32 deckt Aufrufe der Pages API mit einem User- oder App-Access-Token ab.

Sagt x-app-usage, wann die Sperre endet?

Nein. Er trägt drei Prozentwerte und kein Zeitfeld, obwohl Metas Best Practices dir sagen, du sollst ihn auf den Zeitpunkt der Wiederaufnahme prüfen. estimated_time_to_regain_access gehört zum Business-Use-Case-Header, nicht zu diesem.

Erscheint der x-app-usage-Header bei jeder Antwort?

Nein. Meta liefert ihn an Endpunkten, „that receive enough requests from your app“, ein fehlender Header trägt also überhaupt keine Information und darf nie als Nullnutzung gelesen werden.

Welche Anfragen bekommen x-app-usage statt X-Business-Use-Case-Usage?

Graph-API-Anfragen unter den Platform Rate Limits. Anfragen der Marketing API und der Instagram Platform bekommen den Business-Use-Case-Header, und wo beides gelten könnte, sagt Meta, dass die Business-Use-Case-Limits gewinnen.

Was zählt als Nutzer in der Formel 200 mal Nutzer?

Meta versteht darunter die Zahl der eindeutigen täglich aktiven Nutzer einer App. Schwankt die tägliche Nutzung zwischen Wochentagen und Wochenende, werden stattdessen die wöchentlich und monatlich aktiven Nutzer herangezogen. Die Zahl der Installationen spielt dabei keine Rolle, denn Apps mit hohem Engagement erhalten höhere Limits unabhängig von der tatsächlichen Zahl der Installationen.

Kann ein einzelner Nutzer das gesamte Rate Limit einer App aufbrauchen?

Ein einzelner aktiver Nutzer kann das. Meta rechnet selbst vor: Eine App mit 100 Nutzern hat ein Kontingent von 20.000 Aufrufen pro Stunde, und die zehn aktivsten Nutzer könnten davon 19.000 verbrauchen. Das Kontingent wird geteilt statt aufgeteilt, sodass nichts im Platform-Limit ein einzelnes Konto davon abhält, den übrigen Nutzern der App innerhalb derselben Stunde die Quote wegzunehmen.

Spart das Bündeln mehrerer IDs in einer Anfrage Rate-Limit-Kontingent?

Bündeln verringert nicht, was auf das Kontingent angerechnet wird. Laut Metas FAQ zählt jede ID als ein API-Aufruf, sodass drei einzelne Anfragen mit je einer ID und eine Anfrage mit ids=4,5,6 gleichermaßen als drei Aufrufe zählen. Batching verbessert nur die Antwortzeit, nicht das Budget.

Worin unterscheidet sich x-app-usage von X-Ad-Account-Usage?

X-Ad-Account-Usage gibt sein Feld acc_id_util_pct mit Dezimalstellen an, in Metas Beispiel als 9,67, während jedes Feld in x-app-usage auf eine ganze Prozentzahl gerundet wird. X-Ad-Account-Usage enthält außerdem reset_time_duration, ein Feld, das x-app-usage fehlt, und der Header ist an v3.3 und ältere Ads-API-Aufrufe gebunden.