Ce qu'est la limite de taux de l'API Pinterest, par app et par utilisateur

Qu'est-ce que la limite de taux de l'API Pinterest ?

Deux plafonds régissent la limite de taux de l'API Pinterest et c'est le plus bas qui vous arrête : une limite universelle qui s'applique à toutes les requêtes, et une limite par catégorie que Pinterest ajoute par-dessus. La référence des rate limits fixe les chiffres universels à « Trial access: 1000 requests per day for all API requests » et « Standard access: 100 requests per second per user per app for all API requests. »

L'unité change avec le niveau d'accès, et c'est le détail que la plupart des intégrations comprennent de travers. La page des niveaux d'accès de Pinterest l'épelle : « Apps with Trial access are rate limited based on calls per day/per app », tandis que « Apps with Standard access are rate limited at a more granular level at calls per minute/per user/per app. » Une app en Trial dispose d'un seul budget quotidien partagé, quel que soit le nombre de comptes qu'elle sert. Une app en Standard reçoit un budget par minute neuf pour chaque utilisateur connecté.

Chaque endpoint appartient à exactement une catégorie de rate limit, et cette catégorie est publiée dans la description OpenAPI de Pinterest sous la forme d'un champ x-ratelimit-category. Pinterest prévient aussi sur la même page que « all rate limits are subject to change without notice. »

Quelles sont les limites de taux Pinterest par catégorie ?

Douze catégories portent leurs propres chiffres. Les valeurs Trial sont des requêtes par jour par app et les valeurs Standard des requêtes par minute par utilisateur par app, sauf quand la ligne dit autre chose.

De quelle catégorie de limite de taux relève la publication d'un Pin ?

La publication relève de org_write, le budget le plus serré qu'un planificateur touche : 300 appels par jour en Trial et 100 appels par minute en Standard. La description OpenAPI publiée par Pinterest, version 5.28.0 de la Pinterest REST API, étiquette chaque opération directement :

Les Pins vidéo coûtent deux appels org_write au lieu d'un. media/create enregistre l'envoi et renvoie une upload_url, le fichier lui-même part vers cette URL et non vers l'API, puis pins/create attache le média fini. La lecture revient bien moins cher que l'écriture en accès Standard, 1 000 par minute contre 100, et les analyses ne reviennent moins cher ni à l'une ni à l'autre, à 60 par minute. Un tableau de bord qui interroge les analyses Pin par Pin pour 200 Pins heurtera org_analytics bien avant qu'un outil de publication heurte org_write.

Le plafond quotidien de Trial est celui qui attrape ceux qui montent leur première intégration. À 300 appels org_write par jour, une app en Trial crée environ 300 Pins image ou 150 Pins vidéo en 24 heures, partagés entre tous les comptes qui lui sont connectés. Ce budget explique aussi une bonne part des raisons pour lesquelles un Pin ne se publie pas pendant les tests.

Là où les chiffres de Pinterest se contredisent

Pinterest publie des chiffres sur deux pages et dans une spécification, et ils ne se recoupent pas. Trois écarts valent d'être connus avant de dimensionner une file.

La limite universelle de Standard vaut 60 fois la limite de catégorie qu'elle surplombe. La page des rate limits dit que l'accès Standard obtient « 100 requests per second per user per app for all API requests », soit 6 000 par minute. Le tableau des catégories de la même page plafonne org_write à 100 par minute. Le chiffre le plus bas l'emporte, et l'exemple d'en-têtes de Pinterest confirme que plusieurs fenêtres sont appliquées à la fois :

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

Cela se lit comme 100 sur une fenêtre d'une seconde et 1 000 sur une fenêtre de soixante secondes, ce qui ne fait ni 6 000 ni 100.

La limite universelle de Trial est plus haute que deux limites de catégorie situées en dessous. Trial est décrit comme « 1000 requests per day for all API requests », alors que ads_write et org_write sont tous deux listés à 300 par jour dans le tableau des catégories.

L'endpoint des conversions contredit sa propre catégorie. La page des rate limits place ads_conversions à 120 000 requêtes par minute par compte publicitaire par app en Standard. La description de POST /v5/ad_accounts/{ad_account_id}/events, qui porte x-ratelimit-category: ads_conversions, dit dans la spécification publiée par Pinterest : « This endpoint has a rate limit of 5,000 calls per minute per ad account. » Cela fait un facteur 24 entre deux sources Pinterest pour le même endpoint.

Construisez sur le plus petit chiffre de chaque paire. Pinterest ne dit pas quelle page prime.

À quoi ressemble une réponse 429 de Pinterest ?

Chaque endpoint de la spécification documente un 429, décrit comme « the user has sent too many requests in a given amount of time and is being rate limited. » Le corps est l'objet d'erreur générique de Pinterest, un document JSON avec exactement deux champs obligatoires :

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

Cet exemple est celui que Pinterest livre dans la spécification pour le schéma d'erreur partagé, pas un exemple de rate limit. La référence des codes d'erreur de Pinterest liste des codes pour les listes de clients, les audiences et les flux shopping, et ne publie aucun code numérique pour un 429. La spécification ne documente ni en-tête Retry-After ni en-têtes de réponse x-ratelimit-* sur le moindre endpoint, alors même que la page des rate limits montre ces en-têtes dans un exemple cURL. Tenez les en-têtes pour réels et le code numérique pour non documenté, et accrochez votre logique de réessai au statut HTTP plutôt qu'au corps.

Comment rester sous la limite de taux de l'API Pinterest ?

Lisez les compteurs au lieu de les deviner. La méthode documentée par Pinterest consiste à lancer les requêtes en mode verbeux et à inspecter la réponse, comme dans curl -v --location --request GET 'https://api.pinterest.com/v5/pins' --header 'Authorization: Bearer <token>', puis à suivre x-ratelimit-remaining contre x-ratelimit-limit par catégorie plutôt que par app.

Quatre habitudes gardent une intégration dans le budget :

• Budgétez par catégorie, pas par intégration. Un outil de publication, un collecteur d'analyses et une synchronisation de catalogue puisent séparément dans org_write, org_analytics et catalogs_write, si bien que la saturation de l'un ne ralentit pas les autres.
• Étalez les écritures du niveau Standard sur la minute. À 100 appels org_write par minute par utilisateur, une rafale de 200 Pins en file pour un compte demande deux minutes de cadence, la même arithmétique que celle qui régit le budget de points de Bluesky et les 100 publications par 24 heures d'Instagram.
• Sortez de Trial avant le lancement. Trial plafonne org_write à 300 par jour pour toute l'app et, selon la page des niveaux d'accès, les Pins et tableaux créés en Trial « are only visible to their creator as Sandbox entities », donc rien de ce que vous publiez en test n'est public de toute façon.
• Demandez plus quand le réglage par défaut est devenu trop petit. La voie documentée par Pinterest est d'ouvrir un ticket auprès de son équipe support, ce qui est aussi la façon de libérer une place face à la limite de cinq apps que sa FAQ mentionne.

Si vous cadencez une file à la main plutôt qu'avec un client d'API, la même arithmétique par minute s'applique à la programmation de publications Pinterest en masse.

Questions fréquentes

Combien de Pins puis-je créer par jour avec l'API Pinterest ?

En accès Trial, environ 300, parce que pins/create relève de org_write et que Trial plafonne cette catégorie à 300 requêtes par jour par app. En accès Standard, aucun plafond quotidien n'est publié pour org_write, seulement 100 requêtes par minute par utilisateur par app, soit 144 000 par jour si vous teniez ce rythme.

La limite de taux de l'API Pinterest est-elle par app ou par utilisateur ?

Les deux, selon le niveau. L'accès Trial se compte par jour par app, donc tous les comptes connectés partagent un budget. L'accès Standard se compte par minute par utilisateur par app, donc chaque compte connecté a le sien.

Quel code HTTP Pinterest renvoie-t-il en cas de limitation ?

429. La description OpenAPI de Pinterest le définit sur chaque endpoint avec la description « the user has sent too many requests in a given amount of time and is being rate limited », et le corps de la réponse est l'objet d'erreur générique contenant code et message.

Quels en-têtes montrent le quota d'API Pinterest restant ?

x-ratelimit-limit, x-ratelimit-remaining et x-ratelimit-reset. La page des rate limits les montre dans un exemple cURL verbeux, où x-ratelimit-limit porte plus d'une fenêtre, comme dans 100, 100;w=1, 1000;w=60.

Pinterest publie-t-il une valeur Retry-After pour les réponses 429 ?

Non. Ni la page des rate limits ni la description OpenAPI publiée ne définissent Retry-After sur le moindre endpoint. Le seul signal temporel que Pinterest documente est x-ratelimit-reset, montré avec une valeur de 1 dans son propre exemple.

Comment obtenir une limite de taux plus élevée sur l'API Pinterest ?

Passez l'app en accès Standard, puis ouvrez un ticket au support. La page des niveaux d'accès fait passer la montée par My apps et exige un enregistrement vidéo du flux OAuth, et la page des rate limits renvoie quiconque veut un changement supplémentaire vers un ticket auprès du support Pinterest.

Y a-t-il une limite au nombre d'apps que je peux enregistrer chez Pinterest ?

La FAQ de Pinterest mentionne une limite de cinq apps par compte développeur. Le même ticket de support qui permet de demander une limite de taux plus élevée sert aussi à libérer une place une fois cette limite dépassée.

Les Pins vidéo consomment-ils plus de la limite de taux que les Pins image ?

Un Pin vidéo coûte deux appels org_write au lieu d'un, car media/create enregistre l'envoi avant que pins/create attache le fichier terminé. Ce doublement signifie que le budget de 300 appels org_write en accès Trial couvre environ 150 Pins vidéo par jour, soit la moitié de ce qu'il couvre en Pins image seuls.

Les Pins créés en accès Trial sont-ils visibles par d'autres personnes ?

Les Pins et tableaux créés pendant qu'une app est en accès Trial sont des entités Sandbox, visibles uniquement par leur créateur, selon la page des niveaux d'accès de Pinterest. Tester contre le plafond de 300 appels org_write par jour ne coûte donc aucune exposition publique, puisque rien de publié avant le passage à Standard n'est public de toute façon.

L'accès Standard de Pinterest coûte-t-il beaucoup moins cher en lecture qu'en écriture ?

org_read tourne à 1 000 requêtes par minute par utilisateur par app en accès Standard, dix fois les 100 par minute qu'autorise org_write. Analytics se situe sous les deux, à 60 par minute. Cet écart explique pourquoi un tableau de bord qui interroge les analyses de 200 Pins atteint son plafond avant qu'un publicateur atteigne celui d'org_write.