# 排查 API、CLI 和 MCP 連結問題

標準 URL： https://sosoapi.ai/zh-tw/docs/troubleshooting

解決登入、權限、結構描述、上傳及寫入結果不明的失敗，同時避免暴露憑證或重複執行已接受的工作。

## 錯誤瀏覽器或本機登入受阻

停止待處理的登入，再執行 auth login --no-open。在您要使用的瀏覽器使用者設定檔中開啟新輸出的 URL。授權前檢查帳號與工作空間，且同一登入連結僅使用一個瀏覽器使用者設定檔。如果連接埠 8789 已被占用，請確認監聽程序，僅在它是您啟動的登入程序時停止。

```
npx sosoapi auth login --no-open
```

```
lsof -nP -iTCP:8789 -sTCP:LISTEN
```

## 401、403 與不可用帳號

遇到 401，請確認已使用有效憑證登入。遇到 403，請檢查工作空間角色、所選範圍及操作所需能力。使用 auth status 驗證帳號電子郵件與接受的憑證類型。只有操作需要時才變更存取權；切換工具設定檔不會授予權限。

另行檢查社群帳號。讀取連線與能力，只有平台需要重新同意時才重新連結。內部服務錯誤不是重建健康連線的理由。

- [驗證與權限](https://sosoapi.ai/zh-tw/docs/authentication)

- [完整 API 參考](https://sosoapi.ai/zh-tw/docs/api)

## 400 驗證與版本不一致

讀取回應內容與驗證欄位路徑。驗證錯誤可能包含 ZodError；處理常式錯誤可能使用 error、message 及 code 欄位。將請求與已安裝契約比對，並視需要更新用戶端套件。修正錯誤指出的欄位，不要移除必填值或加入不支援的篩選條件。

```
npx sosoapi api contract --route /studio-api/scheduled-posts/
```

## 409、429、5xx 或寫入逾時

遇到 409，請先讀取資源最新版本與可用操作，再進行變更。遇到 429，請依 Retry-After 等待並降低並行數。如果寫入逾時或回傳 5xx，請保留其 ID 並先檢查既有結果：伺服器可能已在連線失敗前接受請求。

只有該操作及目前狀態允許時才重試。相同承載內容請保留相同鍵，不要建立替代項目來繞過不確定結果。重試前先修正驗證失敗。若背景工作仍待處理，其狀態可能已包含值得檢查的執行錯誤。

- [發布參考資料](https://sosoapi.ai/zh-tw/docs/publishing-api-reference)

## 上傳或工具探索問題

本機上傳接受工作目錄、暫存資料夾、Pictures/Movies/Videos 或 SOSOAPI_UPLOAD_ROOTS 所列資料夾內，上限 500 MiB 的支援媒體檔案。拒絕點開頭資料夾，以及超出這些根目錄的符號連結。請加入實際所需媒體資料夾，而非整個家目錄。HTTP 連線無法讀取本機檔案。

如果缺少工具，請重新連結用戶端，並對照參考資料檢查設定檔與連線類型。確認工具已載入目前對話；僅有已儲存的伺服器名稱不足以證明這點。

- [MCP 工具參考](https://sosoapi.ai/zh-tw/docs/mcp)

## 安全分享有用的診斷資訊

分享操作名稱、時間、HTTP 狀態、安全錯誤碼，以及可取得的 request_id 或 x-request-id。請附上 CLI 版本及使用本機或遠端 MCP 的資訊。移除權杖、cookies、授權連結、簽署媒體 URL、客戶內容及私人 ID。請分享相關錯誤，而非憑證檔案或完整回應。

- [聯絡 SosoAPI](https://sosoapi.ai/zh-tw/contact)