Production automation hits the same API errors repeatedly. This table maps symptoms → root cause → fix — verify exact response fields against current Multilogin API docs (endpoints evolve between MLX launcher and cloud API).
HTTP & auth
| Signal | Likely cause | Fix |
|---|---|---|
401 Unauthorized | Expired/rotated API token, wrong Bearer header | Regenerate token; use Authorization: Bearer <token> |
403 Forbidden | Token lacks workspace permission for profile | Check workspace ACL; automation SA in correct folder |
404 Not Found | Wrong profile UUID or deleted profile | Sync profile list via API; validate UUID before queue |
429 Too Many Requests | Launch/stop burst exceeds rate limit | Semaphore 3–5; backoff — see production recipe |
500 / 502 / 503 | Launcher crash, host OOM, update in progress | Retry with jitter; restart Multilogin agent; check disk/RAM |
Profile launch (application-level)
| Symptom | Cause | Fix |
|---|---|---|
| Start returns OK but no CDP URL | Profile still booting; proxy connecting | Poll status 1–2s interval, max 60s timeout |
PROXY_CONNECTION_FAILED | Dead SOCKS/HTTP endpoint, auth typo | Pre-flight proxy check; rotate pool — alignment guide |
| Profile stuck STARTING | Mimic/Stealthfox binary lock, zombie process | Force stop via API; kill orphan browser on host |
| Immediate stop after start | Corrupt profile storage, extension crash | Clone profile; disable extensions; test manual launch |
| CDP connect refused | Firewall blocks local WebSocket port | Allow localhost ports; use launcher-reported host |
Playwright attach errors
connect_over_cdp timeout— CDP URL stale; relaunch profile- Target closed — Profile stopped externally; wrap in try/finally stop
- Execution context destroyed — Navigation during script inject; await load state
Debug snippet (log full 4xx body)
import httpx
def launch(client, headers, profile_id):
r = client.post("/profile/start", headers=headers, json={"profile_id": profile_id})
if r.status_code >= 400:
raise RuntimeError(f"{r.status_code} {r.text}")
return r.json()
Related
Disclosure: MLX-MMO affiliated with Multilogin. Error strings vary by API version — treat as patterns, not guarantees.