Troubleshooting

Most of these come down to network reality or how Pinterest serves its data, not a bug in pin.

A pin-grid feed comes back empty

This is the one to know about. pin reads only what Pinterest serves to a logged-out browser, and two paths back it. Board and profile metadata come from JSON embedded in the page (__PWS_INITIAL_PROPS__); everything that paginates comes from Pinterest's public resource API.

Pinterest's anti-bot defenses vary by source IP. From a residential connection every command returns data. From a datacenter or cloud IP:

• The metadata paths keep working: board show, user show, user boards.
• The pin-grid feeds can return empty even though the HTTP request succeeds (200): get, search, related, topic, trending, board pins, user pins.

When a feed is withheld, pin exits with no results (exit 3) rather than fabricating. This is a property of the network you run from, not a defect. If you need the grid feeds, run from a residential connection. The metadata commands work from anywhere.

Requests start failing or returning 429

Pinterest rate-limits like any public site. pin already paces requests and retries the transient failures, but a hard limit still means backing off. Raise the delay between requests with --rate (for example --rate 1s) and retry later. A burst of 429 or 5xx responses is the site asking you to slow down. A rate limit surfaces as exit 5.

Nothing is found for something you expected

Check that the reference is spelled the way Pinterest uses it: a bare id, a full pinterest.com URL, a user/slug board path, or an @handle. pin ref id <ref> shows how pin classifies what you gave it, with no network call. A genuinely missing pin, board, or profile surfaces as exit 6 (not found).

The binary is not on your PATH

go install puts the binary in $(go env GOPATH)/bin (usually ~/go/bin), and a release archive leaves it wherever you unpacked it. If your shell cannot find pin, add that directory to your PATH. See installation.

Seeing what pin actually did

When something behaves unexpectedly, -v adds per-request detail so you can see the URLs it hit and the responses it got. That is usually enough to tell a rate limit apart from a feed the network withheld. --refresh rules out a stale cache entry.

Exit codes

Every surface reports the same outcome with the same code:

Code	Meaning
0	OK
1	Error
2	Usage error
3	No results (includes a withheld pin-grid feed)
4	Need authentication
5	Rate limited
6	Not found