Claude 的 API 為開發者與個人用戶提供強大的語言模型功能，但在實際呼叫時常遇到密鑰無效、速率限制或權限錯誤。本指南整理最常出現的問題與解決方法，幫助您快速恢復服務。
API 密鑰常見問題
密鑰過期或未啟用是呼叫失敗的主因。首先檢查您的 API 密鑰是否在有效期內，登入 Claude 後台查看密鑰狀態。如果密鑰顯示「已過期」，需要重新產生新密鑰並更新到程式碼中。
另外，密鑰權限不足也會導致「403 Forbidden」錯誤。免費版密鑰只能存取基礎模型，若呼叫進階模型（如 Claude 3.5）會觸發權限限制。建議升級為 Pro 訂閱或調整請求模型。注意不要將密鑰硬編碼在客戶端，以防洩露後被封鎖。
速率限制導致請求被拒
Claude 對 API 呼叫有嚴格的頻率限制，免費用戶每分鐘最多 3 次請求，超出後會收到「429 Too Many Requests」錯誤。解決方案是增加請求間隔，或在迴圈中添加 0.5 秒以上的延遲。批次任務建議使用佇列控制併發數。
此外，每日總請求量也有上限（免費版約 500 次）。達到後需要等到第二天重置或升級到付費方案。可以在後台的 usage 面板即時監控消耗，避免中途斷線。
身份驗證與 Token 錯誤
「Invalid token」錯誤通常因為請求頭中的 Bearer token 格式不對。確保在 Authorization 欄位中寫為 "Bearer YOUR_API_KEY"，不要有多餘空格或換行。另外，部分用戶誤將網頁版的登入 Cookie 當作 API 密鑰使用，兩者不通用，需從 console 中產生專屬密鑰。
如果您使用 OpenClaw 等第三方封裝庫，注意庫版本是否相容 Claude 最新 API。建議參考官方文件更新請求參數，有時模型名稱變更也會導致「model not found」錯誤，例如舊版模型名已被棄用。
網路與超時問題
國內用戶呼叫 Claude API 時經常遇到連線超時或 SSL 憑證錯誤。可以用代理工具（如 Clash）轉發請求，或者設定較長的超時時間（例如 30 秒）。也可以嘗試切換區域節點，部分海外節點對 Claude 的存取更穩定。
如果出現「Connection reset by peer」，通常是網路防火牆攔截了 HTTPS 流量。建議使用企業級代理或直接透過 Claude 官方提供的鏡像連結請求，但務必注意資料安全，避免使用不明第三方介面。
