Troubleshooting
Quick symptom-to-fix reference
| Symptom | Likely cause | Fix |
|---|---|---|
401 on first API call | missing / malformed Authorization header | Add Authorization: Bearer <access_token> |
401 after some time | expired access_token | refresh using refresh token (or reauth) |
400 during token exchange | wrong code_verifier (PKCE) or redirect_uri mismatch | ensure original verifier + exact redirect URI |
| consent screen repeats | requesting new scopes each run | persist granted scopes; request only additions |
| device missing | missing category scope | add required scope; reauthorize |
many 429s | aggressive polling / no backoff | implement exponential backoff with jitter (see Retry & backoff) |
sporadic 5xx | transient upstream issues | retry with limits (see Retry & backoff) |
| slow responses | overly frequent large history windows | narrow time range or paginate |
Checklist to exhaust before seeking help
- Does the redirect URI match exactly (scheme, host, path, trailing slash)?
- Does the scope list include the needed device category?
- Are you using full‑jitter backoff for transient errors (see Retry & backoff)?
- Is
User-Agentheader present and versioned (see Requirements)?