三種 429 錯誤類型
HTTP 429 是標準的「請求過多」狀態碼。這裡涵蓋三種情況,JSON 錯誤主體會告訴您屬於哪一種。
| 錯誤代碼 | 含義 | 典型修復方式 |
|---|---|---|
rate_limited | 每分鐘請求過多 | 減慢速度,將請求分散到一分鐘內 |
concurrency | 同時執行的請求過多 | 降低並行度,等待槽位釋放 |
過載,帶有 Retry-After: 5 | 服務暫時負載,非您的錯 | 等待標頭中的秒數,然後重試 |
先閱讀程式碼,因為一種原因修復方式對另一種原因無效。如果真正問題是 20 個工作程序同時發射請求,將每分鐘請求量減半並不會有幫助。
了解您的限制
限制取決於金鑰類型:
- 完整金鑰: 8 個並行請求,每分鐘 300 個請求。
- 試用金鑰: 2 個並行請求,每分鐘 60 個請求。
每個回應都帶有 X-RateLimit-Limit-Requests 與 X-RateLimit-Limit-Concurrency 標頭,讓你的客戶端能讀取上限,而非硬編碼。試用金鑰通常是新使用者的常見原因:一個每次只執行 1 個請求的腳本,當加入 4 個執行緒的執行緒池時就會開始失敗。試用僅供測試,任何金額 ≥ $20 的儲值即可取得完整金鑰(請參閱 定價頁面 查看金額與贈額)。
上述數字是每個金鑰的配額。如果一個金鑰被網頁應用程式、cron 作業和隊友的筆記型電腦共用,它們都從同一個配額池中消耗,在你將三個工作負載加總之前,429 錯誤看起來會是隨機的。
為什麼串流會增加並行錯誤的機率
一般請求會佔用並行槽位一到兩秒。串流請求(stream: true)會佔用槽位直到最後一個 token 到達且串流關閉。長回答可能會讓槽位佔用數十秒,因此在有多個活躍用戶的聊天應用程式中,8 個槽位會很快耗盡。
這裡的大多數問題由兩個錯誤引起。第一個是放棄串流但未關閉它:如果用戶端停止讀取但保持連線開啟,槽位會保持佔用狀態直到連線結束。請在 finally 區塊中關閉回應,或使用 SDK 的上下文管理器。第二個錯誤是在第一個串流仍存活時開啟第二個串流來重試串流,這會在槽位不足時正好使槽位使用量加倍。
如果您的應用程式需要比金鑰允許的更多同時長串流,請在您的端佇列新聊天,並顯示短暫等待狀態。這比讓用戶看到原始錯誤更好。
帶有指數退避的 Python 重試程式碼
模式很簡單:捕捉 429、讀取程式碼、等待、以遞增延遲和隨機性重試,並在幾次嘗試後放棄。此版本使用官方 openai 套件針對服務的 Base URL:
import random
import time
from openai import OpenAI, RateLimitError
client = OpenAI(
base_url="https://api.onekeyllmapi.com/v1",
api_key="YOUR_KEY",
max_retries=0, # we handle retries ourselves
)
def chat(messages, attempts=5):
for i in range(attempts):
try:
r = client.chat.completions.create(
model="uncensored",
messages=messages,
)
return r.choices[0].message.content
except RateLimitError as e:
headers = e.response.headers
wait = float(headers.get("Retry-After", 0))
if not wait:
wait = min(30, 2 ** i) # 1, 2, 4, 8, 16 seconds
wait += random.uniform(0, 1) # jitter
time.sleep(wait)
raise RuntimeError("still rate limited after retries")
print(chat([{"role": "user", "content": "Reply with the word ok."}]))
當標頭存在時,將其用作最小等待時間。當標頭缺失時,指數延遲對 rate_limited 有效,因為每分鐘視窗會移動。抖動可防止許多工作程序同時重試。
限制並行呼叫的數量上限,讓 429 錯誤鮮少出現
重試僅治標。訊號量可透過不發送超過你的槽位計數的請求來預防大部分情況。將其設定在限制略低的位置,以便重試或意外請求仍有空間:
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(
base_url="https://api.onekeyllmapi.com/v1",
api_key="YOUR_KEY",
)
sem = asyncio.Semaphore(6) # full key allows 8; use 1 on a trial key
async def ask(prompt):
async with sem:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
)
return r.choices[0].message.content
async def main():
prompts = [f"Give one fact about the number {n}." for n in range(50)]
results = await asyncio.gather(*(ask(p) for p in prompts))
print(len(results))
asyncio.run(main())
針對每分鐘限制,每分鐘 300 次請求平均為每秒 5 次。若批次處理數千個短任務,請在訊號量前加入少量延遲或令牌桶。由於 SDK 預設也會自行重試,請明確設定 max_retries,讓你的邏輯與 SDK 的重試機制不會疊加並倍增等待時間。
使用 curl 重現並檢查 429
在更改程式碼之前,請查看原始回應。將 -i 加入 curl 以列印標頭,並同時發送幾個請求以故意引發該錯誤:
for i in 1 2 3 4; do
curl -i -s https://api.onekeyllmapi.com/v1/chat/completions -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"model":"uncensored","messages":[{"role":"user","content":"Count to 200 slowly."}]}' &
done
wait
在允許同時 2 個請求的試用金鑰上,第三和第四次呼叫應返回狀態 429 和錯誤程式碼 concurrency。對於完整金鑰,您需要同時超過 8 個。在每個回覆中查看三件事:狀態行、如果有 Retry-After 標頭,以及 JSON 主體中的 error.code 欄位。這個小實驗比一小時的猜測更有用,並且如果出現異常,可為您提供可向支援部門展示的再現案例。
為它設計,而非繞過它
將 429 視為正常事件,如同超時。將模型呼叫封裝於單一函式中,記錄每次重試及其原因,並公開計數器以便您注意重試率上升。重試率上升是流量已超出單一金鑰限制的早期徵兆,早於用戶抱怨之前。對於聊天產品,每個用戶的小型記憶體佇列可防止一個忙碌帳戶佔用所有 8 個槽位,導致其他人無法使用。
簡短的除錯檢查清單
- 記錄每個 429 的完整錯誤主體和
X-Request-Id標頭。程式碼欄位區分rate_limited和concurrency。 - 檢查您的金鑰是否為試用金鑰。如果是,預期為每分鐘 60 次請求,且並行請求為 2 個。
- 計算使用金鑰的每個程式,不僅是失敗的那個。
- 尋找未關閉的串流,以及沒有延遲立即重試的迴圈。立即重試迴圈會將一個 429 變成一百個。
- 透過
X-Balance-USD或GET /v1/balance確認餘額。餘額為空是與 429 不同的問題,但檢查只需幾秒鐘。
失敗的請求不會收費,因此重試不會因被拒絕的嘗試而消耗您的 token。如需狀態碼和標頭的完整列表,請參見 文件。如果您需要比試用金鑰具有更高限制的金鑰,取得 API 金鑰 並儲值。
