繁中 ▾
取得 API 金鑰

LLM API 錯誤 429:原因與解決方法

LLM API 錯誤 429 表示伺服器目前拒絕請求,並非永久拒絕。在此 API 中有三種不同的原因,每種都需要稍微不同的修復方式。

更新於

光線封包在八車道門前排隊,說明 API 速率限制

重點摘要

三種 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 個槽位,導致其他人無法使用。

簡短的除錯檢查清單

  1. 記錄每個 429 的完整錯誤主體和 X-Request-Id 標頭。程式碼欄位區分 rate_limited 和 concurrency。
  2. 檢查您的金鑰是否為試用金鑰。如果是,預期為每分鐘 60 次請求,且並行請求為 2 個。
  3. 計算使用金鑰的每個程式,不僅是失敗的那個。
  4. 尋找未關閉的串流,以及沒有延遲立即重試的迴圈。立即重試迴圈會將一個 429 變成一百個。
  5. 透過 X-Balance-USD 或 GET /v1/balance 確認餘額。餘額為空是與 429 不同的問題,但檢查只需幾秒鐘。

失敗的請求不會收費,因此重試不會因被拒絕的嘗試而消耗您的 token。如需狀態碼和標頭的完整列表,請參見 文件。如果您需要比試用金鑰具有更高限制的金鑰,取得 API 金鑰 並儲值。

問答

429 是你的錯還是供應商的錯?

兩者皆有可能。代碼 rate_limited 和 concurrency 表示你的金鑰已超過限制。帶有 Retry-After 標頭的 429 也可能來自暫時過載,等待指定時間後重試是正確的回應方式。

我應該等多久再重試?

如果回應包含 Retry-After 標頭,請至少等待該秒數。否則從一秒開始,每次加倍延遲時間,並加入少量隨機抖動。

被拒絕的請求會收費嗎?

不會。失敗或被拒絕的請求不會收費。

我可以提高限制嗎?

完整金鑰允許 8 個並行請求和每分鐘 300 個,而試用金鑰僅為 2 個並行請求和每分鐘 60 個。超出此範圍後,請在您的佇列分散工作。

只差一張表單,即可取得金鑰

建立帳號、複製金鑰、更改基礎 URL。這就是整個設定過程。