Así funciona el límite de tasa de la API de Pinterest, por app y por usuario

¿Qué es el límite de tasa de la API de Pinterest?

Dos techos gobiernan el límite de tasa de la API de Pinterest y el más bajo es el que te frena: un límite universal que se aplica a todas las solicitudes y un límite por categoría que Pinterest añade encima. La referencia de rate limits fija las cifras universales en "Trial access: 1000 requests per day for all API requests" y "Standard access: 100 requests per second per user per app for all API requests."

La unidad cambia con el nivel de acceso, y ese es el detalle que la mayoría de las integraciones entiende mal. La página de niveles de acceso de Pinterest lo deletrea: "Apps with Trial access are rate limited based on calls per day/per app", mientras que "Apps with Standard access are rate limited at a more granular level at calls per minute/per user/per app." Una app en Trial tiene un único presupuesto diario compartido sin importar a cuántas cuentas sirva. Una app en Standard recibe un presupuesto por minuto nuevo para cada usuario conectado.

Cada endpoint pertenece exactamente a una categoría de rate limit, y la categoría se publica en la propia descripción OpenAPI de Pinterest como el campo x-ratelimit-category. Pinterest avisa además en esa misma página de que "all rate limits are subject to change without notice."

¿Cuáles son los límites de tasa de Pinterest en cada categoría?

Doce categorías llevan sus propias cifras. Las de Trial son solicitudes por día por app y las de Standard son solicitudes por minuto por usuario por app, salvo donde la fila diga otra cosa.

¿En qué categoría de límite de tasa entra publicar un Pin?

Publicar cae bajo org_write, el presupuesto más ajustado que toca un programador de publicaciones: 300 llamadas al día en Trial y 100 llamadas por minuto en Standard. La descripción OpenAPI publicada de Pinterest, versión 5.28.0 de la Pinterest REST API, etiqueta cada operación directamente:

Los Pines de vídeo cuestan dos llamadas org_write en lugar de una. media/create registra la subida y devuelve una upload_url, el archivo en sí se envía a esa URL y no a la API, y pins/create adjunta después el medio terminado. Leer sale mucho más barato que escribir en el acceso Standard, 1,000 por minuto frente a 100, y las analíticas no salen más baratas que ninguno de los dos, con 60 por minuto. Un panel que consulta analíticas Pin a Pin para 200 Pines chocará con org_analytics mucho antes de que un publicador choque con org_write.

El techo diario de Trial es el que pilla a quien monta su primera integración. Con 300 llamadas org_write al día, una app en Trial crea unos 300 Pines de imagen o 150 Pines de vídeo en 24 horas, repartidos entre todas las cuentas conectadas a ella. Ese presupuesto también explica buena parte de los motivos por los que un Pin no se publica durante las pruebas.

Dónde las propias cifras de Pinterest no cuadran

Pinterest publica cifras en dos páginas y en una especificación, y no encajan entre sí. Conviene conocer tres huecos antes de dimensionar una cola.

El límite universal de Standard es 60 veces el límite de categoría que tiene debajo. La página de rate limits dice que el acceso Standard recibe "100 requests per second per user per app for all API requests", lo que sale a 6,000 por minuto. La tabla de categorías de esa misma página topa org_write en 100 por minuto. Gana la cifra más baja, y el propio ejemplo de cabeceras de Pinterest confirma que se aplica más de una ventana a la vez:

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

Eso se lee como 100 en una ventana de un segundo y 1,000 en una ventana de sesenta segundos, que no es ni 6,000 ni 100.

El límite universal de Trial es más alto que dos límites de categoría que tiene debajo. Trial se describe como "1000 requests per day for all API requests", y sin embargo ads_write y org_write aparecen ambos con 300 al día en la tabla de categorías.

El endpoint de conversiones contradice a su propia categoría. La página de rate limits sitúa ads_conversions en 120,000 solicitudes por minuto por cuenta publicitaria por app en Standard. La descripción de POST /v5/ad_accounts/{ad_account_id}/events, que lleva x-ratelimit-category: ads_conversions, dice en la especificación publicada de Pinterest: "This endpoint has a rate limit of 5,000 calls per minute per ad account." Eso es un factor de 24 entre dos fuentes de Pinterest para el mismo endpoint.

Construye contra la cifra más pequeña de cada par. Pinterest no dice qué página tiene prioridad.

¿Cómo es una respuesta 429 de Pinterest?

Cada endpoint de la especificación documenta un 429, descrito como "the user has sent too many requests in a given amount of time and is being rate limited." El cuerpo es el objeto de error genérico de Pinterest, un documento JSON con exactamente dos campos obligatorios:

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

Ese ejemplo es el que Pinterest incluye en la especificación para el esquema de error compartido, no un ejemplo de rate limit. La referencia de códigos de error de Pinterest enumera códigos para listas de clientes, audiencias y feeds de compras, y no publica ningún code numérico para un 429. La especificación no documenta ninguna cabecera Retry-After ni cabeceras de respuesta x-ratelimit-* en ningún endpoint, aunque la página de rate limits enseñe esas cabeceras en un ejemplo de cURL. Trata las cabeceras como reales y el código numérico como indocumentado, y ata tu lógica de reintento al estado HTTP y no al cuerpo.

¿Cómo te mantienes por debajo del límite de tasa de la API de Pinterest?

Lee los contadores en vez de adivinarlos. El método documentado por Pinterest es lanzar las solicitudes en modo verboso e inspeccionar la respuesta, como en curl -v --location --request GET 'https://api.pinterest.com/v5/pins' --header 'Authorization: Bearer <token>', y después seguir x-ratelimit-remaining contra x-ratelimit-limit por categoría y no por app.

Cuatro hábitos mantienen una integración dentro del presupuesto:

• Presupuesta por categoría, no por integración. Un publicador, un sondeo de analíticas y una sincronización de catálogo tiran de org_write, org_analytics y catalogs_write por separado, así que uno saturado no frena a los otros.
• Reparte las escrituras del nivel Standard a lo largo del minuto. Con 100 llamadas org_write por minuto por usuario, una ráfaga de 200 Pines en cola para una cuenta necesita dos minutos de ritmo, la misma aritmética que gobierna el presupuesto de puntos de Bluesky y los 100 posts por 24 horas de Instagram.
• Sal de Trial antes del lanzamiento. Trial topa org_write en 300 al día para toda la app y, según la página de niveles de acceso, los Pines y tableros creados en Trial "are only visible to their creator as Sandbox entities", así que nada de lo que publiques en pruebas es público de todos modos.
• Pide más cuando se te haya quedado pequeño lo que viene por defecto. La vía documentada por Pinterest es abrir un ticket con su equipo de soporte, que es también como liberas un hueco frente al límite de cinco apps que menciona su FAQ.

Si marcas el ritmo de una cola a mano en vez de con un cliente de API, la misma aritmética por minuto se aplica a programar publicaciones de Pinterest en masa.

Preguntas frecuentes

¿Cuántos Pines puedo crear por día con la API de Pinterest?

En acceso Trial, unos 300, porque pins/create cae bajo org_write y Trial topa esa categoría en 300 solicitudes por día por app. En acceso Standard no hay tope diario publicado para org_write, solo 100 solicitudes por minuto por usuario por app, que son 144,000 al día si lo sostuvieras.

¿El límite de tasa de la API de Pinterest es por app o por usuario?

Los dos, según el nivel. El acceso Trial se mide por día por app, así que todas las cuentas conectadas comparten un presupuesto. El acceso Standard se mide por minuto por usuario por app, así que cada cuenta conectada tiene el suyo.

¿Qué código de estado HTTP devuelve Pinterest al limitar la tasa?

429. La descripción OpenAPI de Pinterest lo define en cada endpoint con la descripción "the user has sent too many requests in a given amount of time and is being rate limited", y el cuerpo de la respuesta es el objeto de error genérico con code y message.

¿Qué cabeceras muestran mi cuota restante de la API de Pinterest?

x-ratelimit-limit, x-ratelimit-remaining y x-ratelimit-reset. La página de rate limits las muestra en un ejemplo verboso de cURL, con x-ratelimit-limit llevando más de una ventana, como en 100, 100;w=1, 1000;w=60.

¿Pinterest publica un valor Retry-After para las respuestas 429?

No. Ni la página de rate limits ni la descripción OpenAPI publicada definen Retry-After en ningún endpoint. La única señal temporal que Pinterest documenta es x-ratelimit-reset, mostrada con un valor de 1 en su propio ejemplo.

¿Cómo consigo un límite de tasa más alto en la API de Pinterest?

Sube la app a acceso Standard y después abre un ticket de soporte. La página de niveles de acceso encamina la mejora por My apps y exige una grabación en vídeo del flujo de OAuth, y la página de rate limits manda a quien quiera un cambio adicional a abrir un ticket con el soporte de Pinterest.

¿Hay un límite en la cantidad de apps que puedo registrar en Pinterest?

El propio FAQ de Pinterest menciona un límite de cinco apps por cuenta de desarrollador. La misma vía de ticket de soporte que sirve para pedir un límite de tasa más alto es la que libera un cupo una vez que superas ese límite.

¿Los Pines de video consumen más del límite de tasa que los Pines de imagen?

Un Pin de video cuesta dos llamadas a org_write en lugar de una, porque media/create registra la subida antes de que pins/create adjunte el archivo terminado. Esa duplicación significa que el presupuesto de 300 llamadas de org_write en Trial cubre unos 150 Pines de video al día, la mitad que con Pines de imagen solos.

¿Los Pines creados con acceso Trial son visibles para otras personas?

Los Pines y tableros creados mientras una app tiene acceso Trial son entidades de Sandbox, visibles solo para quien los crea, según la página de niveles de acceso de Pinterest. Probar contra el techo de 300 llamadas diarias de org_write no cuesta exposición pública, porque nada publicado antes de pasar a Standard es público de todos modos.

¿Cuánto más barato es leer que escribir en el acceso Standard de Pinterest?

org_read corre a 1.000 solicitudes por minuto por usuario por app en acceso Standard, diez veces las 100 por minuto que permite org_write. Analytics queda por debajo de ambos con 60 por minuto. Esa diferencia explica por qué un panel que consulta analíticas de 200 Pines llega a su techo antes de que un publicador llegue al de org_write.