錯誤瀏覽器身份或本機登入受阻
先停止待完成登入，再執行 auth login --no-open。喺正確瀏覽器身份開新 URL，同意前核對帳戶及工作空間。唔好用兩個 profile 搶同一連結。8789 port 被佔用時，先識別 listener，只關自己擁有嘅登入 process。
npx sosoapi auth login --no-openlsof -nP -iTCP:8789 -sTCP:LISTEN401、403 及帳戶不可用
401 需要有效登入；403 要核對角色、所選範圍或能力。檢查 auth status、已驗證 email 同操作接受嘅憑證。只有確實操作需要時先由使用者改授權；轉 profile 唔會授權。
平台帳戶資格獨立檢查。重新讀取已連接帳戶及能力資料；只有受影響平台需要更新同意先重新連接。唔好為內部服務錯誤重建健康連接。
400 驗證及版本差異
檢視實際回應及驗證路徑。部分驗證錯誤用 ZodError；handler 可能用 error／message／code。對照已安裝 contract，按需要更新主機套件及修正請求。唔好刪必需欄位或自行加未支援 filter。
npx sosoapi api contract --route /studio-api/scheduled-posts/409、429、5xx 或寫入逾時
遇 conflict 先讀最新資源版本及可用操作。429 要跟 Retry-After 同減低並發。寫入期間逾時或 5xx，要保留 ID 並先查目前結果；連接中斷後請求仍可能已接受。
依照操作指定重試資格。唔好用同一 idempotency key 傳唔同 payload、另建 ID 繞過未明結果，或原樣重試授權失敗。背景 job 就算仍係 pending，狀態亦可能已記錄執行錯誤。
上傳或工具載入問題
本機上傳接受真實支援媒體，最大 500 MiB，限工作目錄、暫存、Pictures／Movies／Videos 及指定 SOSOAPI_UPLOAD_ROOTS。隱藏目錄同越過允許根目錄嘅 symlink 會被拒絕。只授予指定媒體目錄，唔好開放整個 home。HTTP 工具唔能夠讀你部電腦。
工具欠缺時重新連接主機，對照參考檢查 transport／profile。只係登記咗 server 名唔代表目前對話已載入連接。
安全分享診斷資料
記錄操作名、時間、HTTP 狀態、安全 error code 同可用 request_id／x-request-id，加 CLI 版本及 local／remote。分享前移除 token、cookies、授權 URL、signed media URL、客戶內容及私人 ID。唔好貼原始憑證檔或完整回應。