重點整理
- Context windows combine prompt and completion, so long histories drain limits faster than expected.
- 串流需要謹慎處理 SSE 事件，以避免 JSON 損毀或 token 遺失。
- JSON mode demands strict schema adherence; malformed responses cause silent parsing failures.
- 預付式加密貨幣計費方式讓錯誤免費，但記帳必須精確以避免意外。
為什麼您的 API 金鑰可能會被拒絕
當用戶端傳送格式錯誤的標頭或超出請求主體限制時，API 金鑰會被拒絕。伺服器會在處理任何邏輯之前驗證身份驗證標頭。如果標頭遺失或包含額外的空白字元，請求將立即失敗。
另一個常見的原因是傳送的 payload 超過 8 MB 的 body 大小限制。具有許多訊息的大型 context window 很容易超過此閾值。在傳送前，請檢查您的訊息陣列長度和 token 計數。
- 確保 Authorization 標頭正確使用 'Bearer' 前綴。
- Verify the request body size stays under 8 MB.
- 檢查 API 金鑰是否有效且未過期。
了解上下文窗口限制
上下文視窗包含輸入提示和生成的補全。我們的 API 支援 100,000 token 的視窗，但你必須同時考慮兩邊。如果你發送 80,000 token 的上下文，那麼只剩下 20,000 可用於回應。
如果您未指定 max_tokens，大多數模型預設會使用較小的輸出限制。這可能會意外截斷較長的回答。僅在您希望設定上限時，才將 max_tokens 設為您想要的長度。請注意，該限制適用於整個請求，而不僅是提示詞。
正確處理串流中斷
透過伺服器發送事件（SSE）進行串流需要穩健的錯誤處理機制。如果連線中斷，您可能會遺失最後一個 token 或使用量元數據。請務必緩衝收到的資料片段，並在客戶端重構完整的回應。
Token 使用資料通常會在串流的最後一個區塊中傳送。如果您提前關閉連線，可能會錯過精確的 token 計數。這會影響預付系統的計費準確性。請實作具有指數退避機制的重試機制，以處理暫時性的網路問題。
使用專門的串流客戶端，自動處理 SSE 解析。這可降低解析錯誤的風險，並確保您能擷取所有資料。
JSON 模式解析錯誤
使用 response_format: {"type": "json_object"} 時，模型必須回傳有效的 JSON。任何偏差都會導致應用程式出現解析錯誤。請確保您的提示詞明確指示模型僅輸出 JSON。
有時模型會在 JSON 周圍加上 Markdown 程式碼區塊，這會導致嚴格解析器出錯。在解析前請移除 包裝。此外，在將資料投入使用前，請先在客戶端驗證 JSON 結構。
使用架構驗證庫來及早偵測錯誤。這可防止模型返回意外鍵或類型時發生崩潰。
Token計費與計數的意外
預付計費僅針對實際使用的 token 收費。錯誤和拒絕回應皆免費，這相較於訂閱制模型是一大優勢。然而，若不考慮整個上下文，token 計數可能會變得複雜。
對話歷史中的每則訊息都會計入輸入 token 上限。長對話會比您預期的更快耗盡您的預付額度。請定期監控您的使用情況，以避免在會話中途耗盡額度。
設定低餘額提醒。這樣可以確保在請求失敗前進行充值。請記住，餘額不會過期，因此您可以在任何方便時進行充值。
避免 NSFW 提示中的軟性拒絕
當模型猶豫不決或提供部分答案而非直接回應時，就會發生軟性拒絕。這通常發生在具爭議性或成人主題上。即使在無審查的模型中，某些觸發因素仍可能導致猶豫。
調整 temperature 參數以降低隨機性。較低的 temperature 值會使模型更具決定性，且較不會使用模糊的措辭。此外，請確保您的提示詞清晰明確。避免使用可能讓模型產生混淆的含糊語言。
如果您遇到頻繁的軟性拒絕，請嘗試稍微重寫提示詞。文字上的小調整通常可以繞過猶豫，獲得直接的回答。
速率限制尖峰與退避策略
該 API 允許每分鐘 300 次請求，且每個金鑰允許 8 個同時請求。流量突增可能會迅速達到這些限制。請實作指數退避演算法，以優雅地處理速率限制錯誤。
當收到 429 狀態碼時，請在重試前等待。從短暫延遲開始，並在每次重試時增加延遲時間。這可避免在高峰時段讓伺服器超載。
監控您的請求速率，並相應調整併發層級。如果您正在發出許多同時請求，請考慮將它們分散在時間上。這可確保穩定的吞吐量，同時不會觸及限制。
函式呼叫的 payload 結構
函式呼叫需要特定的 payload 結構。在 tools 參數中定義您的函式，並指定 tool_choice。如果模型判斷函式呼叫為適當的回應，它將回傳函式呼叫。
確保您的函式定義準確且完整。缺少參數或類型錯誤會導致模型產生無效的呼叫。在執行之前，請務必驗證函式呼叫的參數。
使用 tool_choice 參數來控制模型何時呼叫函式。您可以強制呼叫函式、讓模型自行決定，或完全停用函式呼叫。這讓您可以對模型行為進行更精細的控制。
除錯 400 與 500 錯誤
400 錯誤表示客戶端問題，例如 JSON 無效或缺少參數。500 錯誤表示伺服器端問題，例如內部錯誤或逾時。區分這兩種錯誤有助於加快除錯速度。
對於 400 錯誤，請檢查回應中提供的錯誤訊息。它通常會直接指出問題所在。對於 500 錯誤，請在短暫延遲後重試請求。如果錯誤持續發生，請附上請求 ID 聯繫支援團隊。
記錄每個錯誤的請求和回應詳細資訊。這有助於識別模式和重複出現的問題。使用日誌服務來追蹤隨時間變化的錯誤，並改善您的 API 整合。
