Was das Pinterest-API-Rate-Limit ist, pro App und pro Nutzer

Was ist das Pinterest-API-Rate-Limit?

Zwei Obergrenzen regeln das Pinterest-API-Rate-Limit, und die niedrigere ist die, die dich stoppt: ein universelles Limit für alle Anfragen und ein Limit je Kategorie, das Pinterest obendrauf legt. Die Referenz zu Rate-Limits nennt die universellen Zahlen als „Trial access: 1000 requests per day for all API requests“ und „Standard access: 100 requests per second per user per app for all API requests.“

Die Einheit ändert sich mit der Zugangsstufe, und genau dieses Detail bekommen die meisten Integrationen falsch. Pinterests Seite zu den Zugangsstufen schreibt es aus: „Apps with Trial access are rate limited based on calls per day/per app“, während „Apps with Standard access are rate limited at a more granular level at calls per minute/per user/per app.“ Eine Trial-App hat ein einziges gemeinsames Tagesbudget, egal wie viele Konten sie bedient. Eine Standard-App bekommt für jeden verbundenen Nutzer ein frisches Minutenbudget.

Jeder Endpunkt gehört zu genau einer Rate-Limit-Kategorie, und die Kategorie steht in Pinterests eigener OpenAPI-Beschreibung als Feld x-ratelimit-category. Pinterest warnt auf derselben Seite außerdem, dass „all rate limits are subject to change without notice.“

Wie hoch sind die Pinterest-Rate-Limits je Kategorie?

Zwölf Kategorien tragen eigene Zahlen. Trial-Werte sind Anfragen pro Tag pro App, Standard-Werte sind Anfragen pro Minute pro Nutzer pro App, außer wo die Zeile etwas anderes sagt.

Unter welche Rate-Limit-Kategorie fällt das Posten eines Pins?

Das Veröffentlichen fällt unter org_write, das knappste Budget, das ein Scheduler berührt: 300 Aufrufe pro Tag im Trial und 100 Aufrufe pro Minute im Standard. Pinterests veröffentlichte OpenAPI-Beschreibung, Version 5.28.0 der Pinterest REST API, markiert jede Operation direkt:

Video-Pins kosten zwei org_write Aufrufe statt einem. media/create meldet den Upload an und liefert eine upload_url zurück, die Datei selbst geht an diese URL statt an die API, und pins/create hängt danach das fertige Medium an. Lesen ist im Standard-Zugang weit billiger als Schreiben, 1.000 pro Minute gegen 100, und Analytics ist billiger als keines von beidem, bei 60 pro Minute. Ein Dashboard, das Analytics für 200 Pins einzeln abfragt, läuft in org_analytics, lange bevor ein Publisher org_write erreicht.

Die Tagesobergrenze im Trial erwischt die Leute, die ihre erste Integration bauen. Bei 300 org_write Aufrufen pro Tag legt eine App im Trial rund 300 Bild-Pins oder 150 Video-Pins in 24 Stunden an, geteilt über jedes verbundene Konto. Dieses Budget erklärt auch einen guten Teil der Gründe, warum ein Pin nicht veröffentlicht wird, während du testest.

Wo Pinterests eigene Zahlen sich widersprechen

Pinterest veröffentlicht Zahlen auf zwei Seiten und in einer Spezifikation, und sie passen nicht zusammen. Drei Lücken solltest du kennen, bevor du eine Warteschlange dimensionierst.

Das universelle Standard-Limit ist 60 mal so hoch wie das Kategorielimit darunter. Die Seite zu Rate-Limits sagt, Standard-Zugang bekomme „100 requests per second per user per app for all API requests“, was 6.000 pro Minute ergibt. Die Kategorietabelle auf derselben Seite deckelt org_write bei 100 pro Minute. Die kleinere Zahl gewinnt, und Pinterests eigenes Header-Beispiel bestätigt, dass mehr als ein Fenster gleichzeitig durchgesetzt wird:

< x-ratelimit-limit: 100, 100;w=1, 1000;w=60
< x-ratelimit-remaining: 99
< x-ratelimit-reset: 1

Das liest sich als 100 in einem Ein-Sekunden-Fenster und 1.000 in einem Sechzig-Sekunden-Fenster, was weder 6.000 noch 100 ist.

Das universelle Trial-Limit liegt höher als zwei Kategorielimits darunter. Trial wird beschrieben als „1000 requests per day for all API requests“, doch ads_write und org_write stehen beide mit 300 pro Tag in der Kategorietabelle.

Der Conversions-Endpunkt widerspricht seiner eigenen Kategorie. Die Seite zu Rate-Limits setzt ads_conversions im Standard auf 120.000 Anfragen pro Minute pro Werbekonto pro App. Die Beschreibung von POST /v5/ad_accounts/{ad_account_id}/events, die x-ratelimit-category: ads_conversions trägt, sagt in Pinterests veröffentlichter Spezifikation: „This endpoint has a rate limit of 5,000 calls per minute per ad account.“ Das ist ein Faktor 24 zwischen zwei Pinterest-Quellen für denselben Endpunkt.

Baue gegen die kleinere Zahl jedes Paares. Pinterest sagt nicht, welche Seite Vorrang hat.

Wie sieht eine Pinterest-429-Antwort aus?

Jeder Endpunkt in der Spezifikation dokumentiert eine 429, beschrieben als „the user has sent too many requests in a given amount of time and is being rate limited.“ Der Body ist Pinterests generisches Fehlerobjekt, ein JSON-Dokument mit genau zwei Pflichtfeldern:

{
  "code": 2,
  "message": "AdAccount not found."
}

Dieses Beispiel liefert Pinterest in der Spezifikation für das gemeinsame Fehlerschema aus, es ist kein Rate-Limit-Beispiel. Pinterests Referenz zu Fehlercodes listet Codes für Kundenlisten, Zielgruppen und Shopping-Feeds und veröffentlicht überhaupt keinen numerischen code für eine 429. Die Spezifikation dokumentiert weder einen Retry-After Header noch x-ratelimit-* Antwortheader an irgendeinem Endpunkt, obwohl die Seite zu Rate-Limits diese Header in einem cURL-Beispiel vorführt. Behandle die Header als real und den numerischen Code als undokumentiert, und hänge deine Retry-Logik an den HTTP-Status statt an den Body.

Wie bleibst du unter dem Pinterest-API-Rate-Limit?

Lies die Zähler, statt sie zu raten. Pinterests dokumentierte Methode ist, Anfragen im Verbose-Modus zu fahren und die Antwort zu prüfen, wie in curl -v --location --request GET 'https://api.pinterest.com/v5/pins' --header 'Authorization: Bearer <token>', und dann x-ratelimit-remaining gegen x-ratelimit-limit je Kategorie statt je App zu verfolgen.

Vier Gewohnheiten halten eine Integration im Budget:

• Budgetiere je Kategorie, nicht je Integration. Ein Publisher, ein Analytics-Poller und ein Katalog-Sync ziehen getrennt an org_write, org_analytics und catalogs_write, sodass ein saturierter von ihnen die anderen nicht bremst.
• Verteile Schreibvorgänge im Standard-Tier über die Minute. Bei 100 org_write Aufrufen pro Minute pro Nutzer braucht ein Schwall von 200 eingereihten Pins für ein Konto zwei Minuten Taktung, dieselbe Rechnung, die auch Blueskys Punktebudget und Instagrams 100 Posts pro 24 Stunden bestimmt.
• Verlasse das Trial vor dem Start. Trial deckelt org_write bei 300 pro Tag für die ganze App, und laut der Seite zu den Zugangsstufen sind im Trial angelegte Pins und Pinnwände „only visible to their creator as Sandbox entities“, also ist ohnehin nichts öffentlich, was du im Test veröffentlichst.
• Frag nach mehr, wenn du den Standard überwachsen hast. Pinterests dokumentierter Weg ist ein Ticket beim Support-Team, worüber du auch einen Platz gegen die Fünf-App-Grenze frei machst, die seine FAQ erwähnt.

Wenn du eine Warteschlange von Hand taktest statt über einen API-Client, gilt dieselbe Minutenrechnung fürs Planen von Pinterest-Posts in großer Zahl.

Häufig gestellte Fragen

Wie viele Pins kann ich pro Tag über die Pinterest-API anlegen?

Im Trial-Zugang etwa 300, denn pins/create fällt unter org_write, und Trial deckelt diese Kategorie bei 300 Anfragen pro Tag pro App. Im Standard-Zugang gibt es keine veröffentlichte Tagesgrenze für org_write, nur 100 Anfragen pro Minute pro Nutzer pro App, was 144.000 pro Tag wären, wenn du das durchhältst.

Gilt das Pinterest-API-Rate-Limit pro App oder pro Nutzer?

Beides, je nach Stufe. Trial-Zugang wird pro Tag pro App gemessen, also teilen sich alle verbundenen Konten ein Budget. Standard-Zugang wird pro Minute pro Nutzer pro App gemessen, also bekommt jedes verbundene Konto ein eigenes.

Welchen HTTP-Statuscode gibt Pinterest bei einem Rate-Limit zurück?

429. Pinterests OpenAPI-Beschreibung definiert ihn an jedem Endpunkt mit der Beschreibung „the user has sent too many requests in a given amount of time and is being rate limited“, und der Antwort-Body ist das generische Fehlerobjekt mit code und message.

Welche Header zeigen mein verbleibendes Pinterest-API-Kontingent?

x-ratelimit-limit, x-ratelimit-remaining und x-ratelimit-reset. Die Seite zu Rate-Limits zeigt sie in einem Verbose-cURL-Beispiel, wobei x-ratelimit-limit mehr als ein Fenster trägt, wie in 100, 100;w=1, 1000;w=60.

Veröffentlicht Pinterest einen Retry-After-Wert für 429-Antworten?

Nein. Weder die Seite zu Rate-Limits noch die veröffentlichte OpenAPI-Beschreibung definiert Retry-After an irgendeinem Endpunkt. Das einzige Timing-Signal, das Pinterest dokumentiert, ist x-ratelimit-reset, im eigenen Beispiel mit dem Wert 1 gezeigt.

Wie bekomme ich ein höheres Pinterest-API-Rate-Limit?

Stufe die App auf Standard-Zugang hoch und reiche dann ein Support-Ticket ein. Die Seite zu den Zugangsstufen führt das Upgrade über My apps und verlangt eine Videoaufnahme des OAuth-Flows, und die Seite zu Rate-Limits verweist jeden, der eine weitere Änderung will, an ein Ticket beim Pinterest-Support.

Gibt es ein Limit, wie viele Apps ich bei Pinterest registrieren kann?

Pinterests eigenes FAQ nennt ein Limit von fünf Apps pro Entwicklerkonto. Der gleiche Support-Ticket-Weg, über den man ein höheres Rate Limit beantragt, ist auch der Weg, um einen Slot innerhalb dieses Limits freizugeben, sobald man es überschritten hat.

Verbrauchen Video-Pins mehr vom Rate Limit als Bild-Pins?

Ein Video-Pin kostet zwei org_write-Aufrufe statt einem, weil media/create den Upload registriert, bevor pins/create die fertige Datei anhängt. Diese Verdopplung bedeutet, dass das 300-Aufrufe-Budget von org_write bei Trial-Zugang etwa 150 Video-Pins am Tag abdeckt, halb so viele wie bei reinen Bild-Pins.

Sind Pins, die mit Trial-Zugang erstellt wurden, für andere sichtbar?

Pins und Boards, die mit Trial-Zugang einer App erstellt werden, sind laut Pinterests Access-Tiers-Seite Sandbox-Entitäten, die nur für ihren Ersteller sichtbar sind. Das Testen gegen die Obergrenze von 300 org_write-Aufrufen pro Tag kostet also keine öffentliche Sichtbarkeit, da vor dem Upgrade auf Standard-Zugang ohnehin nichts öffentlich ist.

Wie viel günstiger ist Lesen als Schreiben bei Pinterests Standard-Zugang?

org_read läuft bei Standard-Zugang mit 1.000 Anfragen pro Minute pro Nutzer pro App, zehnmal so viel wie die 100 pro Minute, die org_write erlaubt. Analytics liegt mit 60 pro Minute unter beiden. Dieser Abstand erklärt, warum ein Dashboard, das Analytics für 200 Pins abfragt, seine Grenze erreicht, bevor ein Publisher an die Grenze von org_write stößt.