My pin failed

Symptom

A pin’s status is failed and it did not publish to Pinterest.

Cause

A pin reaches failed either because the problem is not retryable (for example a bad payload or a revoked token), or because it exhausted its automatic retries (up to 8 deferrals). Every failed pin carries two fields that tell you why: error_code and error_message.

Fix

1. Read the error

Fetch the pin and look at error_code and error_message:

curl -H "X-API-Key: $PINBRIDGE_API_KEY" \
  "https://api.pinbridge.io/v1/pins/<pin_id>"

{
  "id": "<pin_id>",
  "status": "failed",
  "error_code": "board_access_denied",
  "error_message": "..."
}

2. Match the error code to an action

error_code	What it means	What to do
rate_limited	Pinterest rate limit hit, retries exhausted.	Wait, then retry. Slow your publish rate. See My pin is stuck in queued.
token_expired	The Pinterest token expired.	Reconnect the account, then retry. See My Pinterest account got disconnected.
token_revoked	The Pinterest token was revoked.	Reconnect the account, then retry.
scope_missing	The token lacks a required Pinterest permission.	Reconnect and grant all requested permissions.
board_access_denied	The account cannot post to that board.	Use a board the account owns or can access.
resource_not_found	The board or a referenced resource no longer exists.	Check the board_id and account.
invalid_payload	Pinterest rejected the pin data.	Fix the pin fields (title, link, media) and retry.
media_url_unreachable	Pinterest could not fetch your image or video URL.	Use a publicly reachable URL, or upload an asset.
media_url_temporarily_unavailable	Your hosted media was briefly unreachable.	Usually transient. Retry.
transient_upstream	A temporary Pinterest or upstream error.	Retry shortly.
publish_timeout	The pin stalled and was failed by the backstop sweep.	Retry. See My pin is stuck in queued.
api_error	Fallback for an unclassified Pinterest error.	Check error_message, fix if clear, then retry.

Other codes can appear for setup or internal issues, including missing_video_asset, asset_not_found, account_not_found, sandbox_board_not_allowed, pinterest_board_environment_mismatch, queue_error, and internal_error. These usually mean a referenced ID is wrong or there was a temporary internal fault. Fix the referenced ID, or retry and contact support if it persists.

3. Retry the pin

Only failed pins can be retried (a non-failed pin returns 409):

curl -X POST -H "X-API-Key: $PINBRIDGE_API_KEY" \
  "https://api.pinbridge.io/v1/pins/<pin_id>/retry"

Retry resets the pin to queued and clears the error. You can override board_id or account_id on retry if that was the problem. For many pins at once, use POST /v1/pins/bulk-retry.

Related

• Error reference — every error by HTTP status, plus the full pin failure code list.
• My Pinterest account got disconnected — for token_expired / token_revoked.
• My pin is stuck in queued — before a pin fails.