了解速率限制與併發請求
速率限制定義了您的 API 金鑰在特定時間視窗內可以處理多少請求，以防止伺服器過載。
Anthropic 同時設定了每分鐘請求數 (RPM) 與每分鐘 token 數 (TPM) 的限制。如果您超過 RPM 上限，會收到 429 Too Many Requests 錯誤。這通常發生在多個執行緒從同一個金鑰發送平行請求時。您必須在客戶端程式碼中實作指數退避機制，以優雅地處理這些重試。
並行請求也很重要。雖然您可能擁有較高的 RPM 限制，但每個金鑰的最大同時連線數通常有上限。如果您運行高吞吐量管線，請監控儀表板上的這些指標。超過並行限制可能會導致請求排隊或連線丟失。
| 限制類型 | 效果 | 解析度 |
|---|---|---|
| RPM | 429 Error | 實作退避 |
| TPM | 速率限制 | 減少批次大小 |
| 並行 | 排隊/捨棄 | 降低並行性 |
處理 Token 上下文視窗錯誤
Token 上下文視窗錯誤發生在您的輸入超過模型支援的最大長度時，導致硬性失敗。
每個模型都有定義的上下文視窗，例如最新變體的 200,000 token。此視窗包含提示和補全。如果您的總 token 數超過此限制，API 會立即返回錯誤。您不能簡單地截斷回應；您必須管理輸入大小。
要避免此問題，請在發送請求前估算 token 數量。使用能準確計算 token 的函式庫。如果您正在處理長文件，請考慮在發送完整文本之前採用分塊策略或摘要。請始終查看模型的文件以了解其特定的上下文長度。
配置兼容性基礎 URL
配置正確的 base URL 可確保您的請求無路由錯誤地到達預期的 Anthropic 伺服器。
標準的 base URL 是 HTTPS://api.anthropic.com。然而，某些地區或特定端點可能會使用不同的 URL。使用錯誤的 base URL 會導致連線超時或 404 錯誤。請務必驗證客戶端設定中的 URL 是否與官方文件相符。
如果您使用的是 OpenAI 相容的包裝程式，請確保基礎 URL 指向正確的代理伺服器。URL 不匹配可能會導致意外行為，例如缺少標頭或錯誤的驗證機制。請仔細檢查環境變數中的基礎 URL 設定。
管理 API 金鑰過期與輪換
API 金鑰過期與輪替：若金鑰遭洩漏，可保護您的帳戶免於未經授權的使用。
部分供應商允許金鑰在設定期限後過期。如果您的金鑰過期，請求將因身份驗證錯誤而失敗。請定期輪換您的金鑰以最小化風險。將金鑰安全地存儲在環境變數或密鑰管理器中，而不是硬編碼在源文件中。
旋轉應在低流量時段進行。生成新密鑰，更新你的客戶端配置，並在撤銷舊密鑰之前驗證功能。這確保零停機時間。保留密鑰創建日期的記錄以預見過期。
除錯串流回應問題
串流回應問題通常源於對伺服器推送事件 (SSE) 的處理不當或缺少標頭。
串流處理時，API 以區塊形式發送數據。您的客戶端必須正確解析這些區塊。如果您錯過一個區塊或未能處理最後一個事件，您的應用程式可能會掛起或顯示不完整的文本。確保您的程式碼監聽串流事件類型，並在每個權重到達時處理它們。
常見錯誤包括忽略 stop_reason field or failing to close the stream connection. Always handle errors within the stream to prevent resource leaks. Use libraries that abstract the streaming logic if you are building a custom client.
最佳化提示詞結構以實現成本效率
最佳化提示詞結構可降低 token 使用量，在維持輸出品質的同時降低您的成本。
提示詞中的每個 Token 都會產生費用。移除不必要的空白、冗餘的指示和過多的範例。使用簡潔的語言和結構化的格式（如 JSON 或 XML）來提供清晰的指示。這將顯著減少輸入 Token 的數量。
考慮使用系統提示詞進行一般指示，使用使用者提示詞進行特定任務。這種分離可以提高模型效能並減少重複上下文的需求。在儀表板中監控您的 token 使用情況，以識別低效的提示詞。根據使用數據調整提示詞，以優化成本。
工具呼叫（Tool Calling）實作的常見錯誤
工具調用錯誤通常涉及不正確的 JSON 模式或對工具回應的不當處理。
使用工具時，請準確定義 JSON 架構。類型或必要欄位不匹配會導致模型無法生成有效的工具呼叫。確保您的客戶端程式碼能解析工具呼叫參數並正確執行函式。以模型預期的格式返回結果，以便模型繼續執行。
另一個常見的錯誤是未能優雅地處理工具錯誤。如果工具失敗，請向模型返回錯誤訊息，以便它進行重試或調整。這能提高您應用程式的整體可靠性。在部署至生產環境之前，請徹底測試您的工具定義。
API 金鑰的安全性最佳實踐
安全性最佳實踐可防止未經授權存取您的 API 資源，並降低計費欺詐的風險。
Never share your API key in public repositories or client-side code. Use environment variables or secret management services to store keys. Rotate keys regularly and revoke unused keys. Monitor your API usage for unusual patterns, such as sudden spikes in token consumption.
如果您的供應商支援，請實作 IP 白名單。這能透過限制存取至已知 IP 位址來增加一層安全性。對所有 API 請求使用 HTTPS 以加密傳輸中的資料。定期稽核您的金鑰權限，以確保它們符合應用程式的需求。
