Rate limits & quotas
Runtime throttling, monthly pin-creation quotas, and the billing errors that enforce them.
Runtime throttling (token buckets)
PinBridge enforces request pacing with Redis-backed token buckets:
- Per Pinterest account — capacity 50 tokens, refill 1.0 token/second.
- Global — capacity 200 tokens, refill 3.0 tokens/second.
Inspect current token availability at any time:
curl "https://api.pinbridge.io/v1/rate-meter?account_id=6f1c2e4a-3b7d-4c9e-8a21-5d0f9b3e7c41" \
-H "X-API-Key: $PINBRIDGE_API_KEY"
The rate-meter needs a connected Pinterest account. Calling it for an account that is not connected returns 404.
Monthly quotas by billing plan
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.
| Plan | Monthly pin creations | Pinterest accounts | Notes |
|---|---|---|---|
| Playground | 50 | 1 | Basic publish flow and board listing |
| Starter | 300 | 2 | Uploaded assets + bulk imports |
| Growth | 1,000 | 5 | Uploaded assets + bulk imports |
| Agency | 5,000 | 15 | Uploaded assets + bulk imports |
| Enterprise | Custom | Custom | Manual setup and custom limits |
The API plan enum value for the Agency plan is pro. Enterprise is sold as “Custom” and is not part of the self-serve catalog. See /pricing/ for current prices.
When the monthly quota is exceeded, POST /v1/pins returns 402 Payment Required with error code quota_exceeded. On paid plans with credits enabled, PinBridge debits 1 credit per pin after the monthly quota is used up. See Billing & credits.
Billing and limit errors
402 billing_inactive— subscription is not active or trialing on a paid plan.402 quota_exceeded— monthly pin-creation quota reached (and credits are not applicable).402 credits_exhausted— quota reached, credits are enabled, and the balance is 0.403 plan_limit— Pinterest account connection limit reached for your plan.
Pinterest platform limits
Pinterest applies its own upstream limits. PinBridge handles Pinterest 429 responses by backing off and retrying in worker processing where appropriate, so a Pinterest-side throttle does not fail your publish outright.
Good to know
- PinBridge does not currently emit universal
X-RateLimit-*headers on every response. For live throttling visibility, useGET /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.
Next steps
- Billing & credits — plans, what counts against quota, and credit packs.
- Authentication — get an API key before you publish.
- Quickstart — connect Pinterest and publish your first pin.
- Python SDK — read the rate-meter and billing status from code.