Advanced Topics
Rate Limits
Runtime throttling, monthly pin creation quotas, and plan limits
Runtime Throttling (Token Buckets)
PinBridge enforces request pacing with Redis-backed token buckets:
- Per Pinterest account bucket
- Capacity:
50tokens - Refill rate:
1.0token/second
- Capacity:
- Global bucket
- Capacity:
200tokens - Refill rate:
3.0tokens/second
- Capacity:
Use this endpoint to inspect current token availability:
GET /v1/rate-meter?account_id=<pinterest_account_id>
Monthly Quotas by Billing Plan
| Plan | Monthly Pin Creations | Pinterest Accounts | Notes |
|---|---|---|---|
| Free | 50 | 1 | Basic publish flow and board listing |
| Starter | 300 | 2 | Uploaded assets + bulk imports |
| Growth | 1,000 | 5 | Uploaded assets + bulk imports |
| Pro | 5,000 | 15 | Uploaded assets + bulk imports |
| Enterprise | 100,000 | 50 | Manual setup and custom limits |
Only successful new pin creations count against this quota. That includes direct POST /v1/pins, successful import rows, and successful scheduled publishes. Reads, auth, board sync, webhooks, invalid rows, and idempotent retries do not.
When monthly quota is exceeded, POST /v1/pins returns 402 Payment Required with error code quota_exceeded.
Billing and Limit Errors
Common enforcement responses:
402 billing_inactive— subscription is not active/trialing on paid plans402 quota_exceeded— monthly pin creation quota reached403 plan_limit— Pinterest account connection limit reached
Pinterest Platform Limits
Pinterest applies its own upstream limits. PinBridge handles Pinterest 429 responses by backing off and retrying in worker processing where appropriate.
Important Notes
- PinBridge does not currently emit universal
X-RateLimit-*headers on every API response. - For live throttling visibility, use
GET /v1/rate-meter. - For quota visibility, use
GET /v1/billing/status. - Bulk imports run asynchronously through import jobs. Use
POST /v1/pins/imports/json,POST /v1/pins/imports/csv, andGET /v1/pins/imports/{job_id}to monitor long-running uploads.