Troubleshooting Guide

Fresh

Common Issues

Authentication Issues

Problem	Likely Cause	Solution
401 on every request	Token expired	Refresh token via POST /user/refresh_token
Empty token in signin response	Wrong email/password	Double-check credentials
Token stops working mid-session	30-minute expiry hit	Implement proactive refresh at 25 min
429 Too Many Requests	Rate limit exceeded	Use automation token; add exponential backoff

Profile Issues

Problem	Likely Cause	Solution
Profile won't start	Profile is locked	Use POST /profile/unlock first
400 on profile create	Invalid parameters	Check browser_type and os_type values
Profile starts but no connection	Firewall/network issue	Verify network allows WebSocket connections
Profile data not saving	Profile not stopped cleanly	Always call POST /profile/stop before exiting

2FA Issues

Problem	Likely Cause	Solution
Cannot disable user 2FA	Workspace 2FA still active	Disable workspace 2FA first via POST /workspace/update_2fa
Cannot revoke 2FA device	Only one device remains	Add a new device before revoking the current one
403 on workspace 2FA toggle	Not a workspace admin	Must have admin role to manage workspace 2FA

Diagnostic Decision Tree

Best Practices to Avoid Issues

Token Management

• Refresh tokens at 25 minutes (5 min before expiry)
• Use automation tokens for scripts and bots
• Implement automatic re-auth on 401 responses

Error Handling

• Always check the status.error_code field, not just HTTP status
• Implement exponential backoff for 429 and 5xx errors
• Log full error responses for debugging

2FA Management

• Remember the order: workspace first when enabling, user first when disabling
• Never try to revoke the last 2FA device
• Store device_ids from setup for future management