Troubleshooting

Start with these two commands; between them they explain most problems:

restish pff whoami         # who the API thinks you are, and whether you're entitled
restish doctor api pff     # is Restish's configuration for this API healthy?

Every error the API returns carries a request_id. Quote it if you contact contact@pff.com.

{
  "error": {
    "code": "forbidden",
    "message": "pff-pro requires PFF Pro. Upgrade at https://www.pff.com/subscribe",
    "request_id": "2ea9b59c-2a05-4a26-ad5a-0f3a240676f9",
    "details": { "reason": "subscription_required", "tier": "monthly", "subscribe_url": "https://www.pff.com/subscribe" }
  }
}

Setting up

You see	Cause	Fix
api configure was a Restish v1 command and is not available in v2	Instructions written for Restish 1	restish api connect pff https://api.pff.com
spec discovery failed: GET https://api.pff.com/v1/openapi.json: 401 Unauthorized	You added /v1 to the address — everything under /v1/ needs a credential, and the contract lives at the bare origin	restish api connect pff https://api.pff.com
no API spec found at …	A typo in the address, or the API is unreachable	Check the address is exactly https://api.pff.com, then curl https://api.pff.com/health
unknown command "…" for "restish pff"	The API gained a command since you connected	restish api sync pff
zsh: no matches found: body.leagues[].slug	Your shell expanded the []	Quote the filter, or run restish shell setup zsh once

Signing in and access

You see	Meaning	Fix
401 — The credential has expired	Your cached sign-in could not be refreshed	restish api auth logout pff, then run any command to sign in again
401 — The credential has been revoked	Access was revoked, by you or by support	Sign in again as above; if it repeats, contact support
401 — The credential could not be verified	An API key the API does not recognise: a typo, a key from another environment, or one that was deleted (details.reason: invalid_signature)	Copy the key again or create a new one; every reason is explained in Authentication
401 — That is a session token	You sent a pff.com browser session token instead of an API key or OAuth token (details.reason: wrong_token_type)	Use an API key, or sign in through Restish
403 — pff-pro requires PFF Pro	Your account is PFF+ or free	Upgrade to PFF Pro; whoami shows your tier
403 — The CLI is not included in the Pro trial	Your account is on a Pro trial (details.reason: trial) — the CLI unlocks when it converts to a paid plan	Nothing to fix now; whoami shows entitlement_reason: trial until then
403 — This PFF account is not linked to a subscriber record yet	An account-data problem, not a billing one	Email contact@pff.com with the request_id
whoami still works after restish pff logout	logout ends the API session, not the sign-in Restish cached	Also run restish api auth logout pff

Slow or failing requests

You see	Meaning	Fix
A pause of a few seconds on the first command, or Error: Preparing your session… (503)	The API is setting up your session. Sign-ins are rate-limited upstream, so it queues rather than fails	Nothing — Restish retries automatically. Avoid firing many commands in parallel right after signing in
503 — The identity provider is unavailable	A temporary outage upstream	Retry shortly; check status.pff.com
429 — rate_limited	You’ve used this minute’s read or export budget. The API meters both per account, across every command and both credentials; details.scope says which — api (reads), export (--export true and --format csv), or verify_ip (too many API-key attempts from one address)	Wait the seconds in Retry-After, then retry (Restish does this for you on its first two retries). Every counted response (everything except whoami and logout) carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset — see them with --rsh-headers
429 — upstream_error with details.upstream_status: 429	The data source’s own export metering	Wait for Retry-After. Download a file once instead of re-running exports
502 — upstream_error	The data service didn’t answer	Retry; check status.pff.com

Restish retries 408, 429, 500, 502, 503 and 504 up to two times on its own, honouring the API’s Retry-After. Add --rsh-retry 0 if you’d rather see the first error immediately.

Looking under the hood

restish pff passing --league nfl --season 2025 -v     # request and response headers
restish pff leagues --rsh-headers | grep -i ratelimit  # how much of this minute's read budget is left
restish api inspect pff                                # what Restish stored (secrets masked)
restish pff openapi-json -o json > pff-openapi.json    # the exact contract the CLI was generated from

Still stuck? Email contact@pff.com with the command you ran, the request_id, and the output of restish --version.