Advanced Topics
Queue and Throughput
Understand current queue behavior, rate limits, and practical throughput expectations.
Overview
Queue behavior determines delivery latency under load. High-quality integrations actively shape submission rate and monitor queue/backpressure signals instead of fire-and-forget batching.
What You Will Learn
- How queue depth and backpressure influence publish completion time.
- How to combine client-side throttling with server-side rate and retry behavior.
- How to use queue metrics to protect campaign deadlines.
Implementation Checklist
- Set queue delay SLOs (for example p95 queued-to-publishing transition time).
- Throttle submissions dynamically when rate headroom or success rate degrades.
- Use deterministic idempotency keys to make retries safe under backpressure.
- Prefer imports for large campaigns and single-pin APIs for interactive actions.
- Alert on sustained queue growth, high retry rates, or elevated failure bursts.
Deep Dive
1) Submission shaping strategy
Match submission rate to observed capacity rather than static assumptions.
- Start conservative and ramp based on status outcomes.
- Use lower throughput during upstream instability windows.
- Separate interactive and batch traffic priorities in your own system.
2) Queue health signals that matter
Raw request volume is not enough; focus on delay and outcome trends.
- Track queued duration percentiles and publish success rate together.
- Monitor retry frequency by error class.
- Alert when queued items age beyond campaign tolerance windows.
3) Backpressure-safe retries
Retries should recover from transient failures, not amplify queue pressure.
- Use capped exponential backoff and jitter.
- Retry only transient classes; do not retry validation failures unchanged.
- Pause bulk replay during incident windows until root cause is addressed.
Relevant Endpoints
GET
/v1/rate-meter?account_id=<ACCOUNT_ID>Inspect account/global rate headroom.
GET
/v1/pins/{pin_id}Track per-pin queue/publish lifecycle transitions.
GET
/v1/pins/imports/{job_id}Track batch import progress and row outcomes.
Example
# Pseudocode strategy:
# 1) Submit at low rate
# 2) Observe queue delay + failures
# 3) Increase/decrease rate accordingly
#
# Recommended signal bundle:
# - p95 queued duration
# - publish success rate
# - retry rate per minute
# - rate-meter headroom