Troubleshooting the PinBridge n8n node

Fixes for the problems people hit most often. If your issue is not here, check the Node reference for the exact parameter or endpoint.

The credential test fails

When you save the credential, n8n calls GET /v1/pinterest/accounts. If it fails:

• Wrong base URL. Confirm Base URL is https://api.pinbridge.io (hosted) or your self-hosted API root, with no trailing path. A URL n8n cannot reach fails the test before auth is checked.
• Wrong key type. The API Key field expects a PinBridge API key sent as X-API-Key. A user-session token will not work here.
• Network egress. A self-hosted n8n behind a proxy or firewall must be allowed to reach the base URL.

Full setup steps: Set up your PinBridge credential.

401 invalid key

A 401 means the key was rejected. Two variants:

• Missing API key. No credential was attached, or the key field is empty. Attach the PinBridge API Key credential to the node.
• Invalid API key. The key is wrong, revoked, or from a different project. Generate a fresh key in your project settings and update the credential.

Note the node always authenticates with X-API-Key, even though the API also accepts a Bearer header. Paste an API key, not a JWT.

422 missing account_id (or another required field)

A 422 is a request-validation error. The most common cause on Pin → Publish is a missing Connection, which sends account_id.

• account_id required. Pick a Connection from the dropdown. If the dropdown is empty, your project has no connected Pinterest account yet, or the credential is not valid, so the account list could not load.
• Media source. You must set exactly one of Image URL or Asset ID (via Media Source). Both missing, or both present, returns 422.
• Field limits. Title max 100, Description max 800, Alt Text max 500, Link URL max 2048, Dominant Color must be 6-digit hex. Idempotency Key is required (leave the default expression in place).

Binary property not found

Upload Image, Upload Video, and Import CSV read the file from the Binary Property field (binaryPropertyName, default data). If the operation errors that the binary property is missing:

• Name mismatch. The upstream node output the file under a different property name. Set Binary Property to match it (check the previous node’s output for the binary key), or rename it with a Move Binary Data / Edit Fields node.
• No binary at all. The incoming item has JSON but no binary data. Make sure the previous node actually produces a file (for example an HTTP Request with response format “File”, or Read Binary File).

See Upload images and video.

Why Limit does not reduce API calls (boards, connections, webhooks)

For Board → List, Connection → List, and Webhook → List, the node fetches the entire collection from the API, then slices the result to your Limit on the client. So:

• Setting a small Limit trims the node’s output but does not make the API return less or run faster.
• On a large account, the full list still loads. Plan for that if you have many boards.

By contrast, Pin → List, Pin → List Imports, and Schedule → List page on the server, so their Limit does reduce the fetch. Details in the Node reference.

Not receiving pin events

Events reach n8n only through the generic Webhook node, since the package ships no trigger node.

• Workflow not active. The Webhook node must use its Production URL and the workflow must be activated. A test URL only fires during a manual “Listen for test event”.
• URL not registered. You must register the Webhook node’s URL with PinBridge via Webhook → Create. Confirm with Webhook → List.
• Wrong events. Only pin.published and pin.failed are ever sent. Subscribing to any other name delivers nothing.
• Delivery failing. A delivery counts as success only on a 2xx response, retries up to 5 times, and each attempt times out at 30 seconds. If your workflow is slow or errors, deliveries are retried then dropped. Return 2xx quickly.
• Event name looks missing. The event type is in the X-PinBridge-Event header, not the JSON body. Read it from ={{$json["headers"]["x-pinbridge-event"]}}.

Full setup: Receive pin events with a webhook.

Signature verification fails

The X-PinBridge-Signature header is HMAC-SHA256 (hex) over the raw JSON body only.

• Verify before reshaping. Compute the HMAC on the raw body, before any node changes the JSON. Enable Raw Body on the Webhook node.
• Secret mismatch. Use the exact secret you set on Webhook → Create. If you rotated it with Webhook → Update, use the new value.
• No timestamp. The signed string is the body alone; there is no timestamp header to include.

A pin failed: reading the error

When a pin ends in failed, read its error_code. Common values: rate_limited, token_expired, token_revoked, scope_missing, board_access_denied, media_url_unreachable, media_url_temporarily_unavailable, resource_not_found, invalid_payload, and publish_timeout. Retryable failures auto-retry (queued to deferred, up to 8 deferrals) before ending in failed.

Next steps

• Node reference — exact parameters and endpoints.
• Publish your first pin — a known-good baseline flow.
• Set up your PinBridge credential — recheck your credential.