My pin is stuck in queued

Symptom

You created a pin, but its status stays queued (or deferred) instead of moving to published.

Cause

A pin flows through these states:

queued → publishing → published, or failed.

Retryable problems (a temporary Pinterest rate limit or upstream hiccup) send the pin queued → deferred, where it waits for an automatic retry rather than failing.

• queued means the pin is waiting for a worker to pick it up, or waiting out a short retry delay (around 60 seconds plus jitter for transient errors).
• deferred means the pin has already been retried a few times and is now parked for a longer wait (about an hour) before trying again. PinBridge defers up to 8 times before giving up and marking the pin failed.

So a pin sitting in queued or deferred for a while is usually normal: it is being retried automatically. You do not need to do anything.

Fix

1. Wait for the automatic retry. Deferred pins retry roughly hourly. Transient queued pins retry within a minute or two. There is no need to resubmit.
2. Check the rate meter. If many pins are queued at once, you may be near Pinterest’s rate limit. Check GET /v1/rate-meter?account_id=6f1c2e4a-3b7d-4c9e-8a21-5d0f9b3e7c41:

bash
curl -H "X-API-Key: $PINBRIDGE_API_KEY" \
"https://api.pinbridge.io/v1/rate-meter?account_id=6f1c2e4a-3b7d-4c9e-8a21-5d0f9b3e7c41"

3. Do not retry a queued or deferred pin manually. The retry endpoint only accepts failed pins, so calling it on a queued pin returns 409. See My pin failed.
4. Backstop recovery. If a pin somehow stalls in queued or publishing for a long time, PinBridge’s stuck-pin sweep re-drives it automatically. A pin idle past roughly 10 minutes is re-queued; one idle past about 6 hours is failed with error_code = publish_timeout. If you see publish_timeout, treat it like any failure and retry it.

When to worry

If a pin reaches failed, it is done retrying. Read its error_code and act on it. See My pin failed.

Related

• My pin failed — read a failed pin’s error code.
• Error reference — all API errors.
• Troubleshooting — all articles.