Lỗi 429 nghĩa là traffic của bạn đã vượt một giới hạn tốc độ: số request mỗi phút, số request đang chạy, số token mỗi phút hoặc chi tiêu. Hãy xử lý theo hai nửa. Retry cho đúng: exponential backoff có trần kèm jitter ngẫu nhiên, tuân theo Retry-After. Gửi ít hơn cùng lúc: một semaphore đặt bằng hạn mức request đang chạy của key, cộng với một hàng đợi. Cả hai đều có ở bên dưới, kèm code.
Để xem bảng mã trạng thái đầy đủ, hãy đọc hướng dẫn lỗi và retry; với agent chạy nhiều giờ có checkpoint và timeout, xem agent chạy dài: timeout và retry.
429 khác 5xx thế nào?
| Trạng thái | Vấn đề của ai | Retry? | Cách làm |
|---|---|---|---|
| 429 | Traffic của bạn vượt giới hạn | Có | Backoff có jitter; tuân theo Retry-After; giảm số request đồng thời |
| 500 / 502 / 503 / 504 | Phía server | Có | Exponential backoff có giới hạn |
| Kết nối bị reset, timeout | Mạng hoặc server | Thường là có | Backoff; với stream, chỉ khi chấp nhận bị tính phí lại |
| 400 / 422 | Request sai | Không | Sửa payload |
| 401 / 402 / 403 | Key, số dư hoặc chính sách | Không | Sửa key, nạp tiền vào tài khoản, sửa danh sách cho phép |
| 413 | Request quá lớn | Không | Thu nhỏ request |
Trên BroadNet Inference, lỗi 429 có thể đến từ bất kỳ giới hạn nào trong bốn loại: tốc độ, đồng thời, tốc độ token hoặc chi tiêu. Giới hạn chi tiêu sẽ không tự hết sau 30 giây. Tài liệu của BroadNet không nói trường nào trong body lỗi cho biết giới hạn nào, nên hãy ghi log body và so với các giới hạn hiển thị trong chi tiết key của bạn.
Bộ dữ liệu mở gói miễn phí và giới hạn tốc độ của API LLM so sánh những gì 14 nhà cung cấp công bố về quyền dùng miễn phí, giới hạn tốc độ ban đầu, yêu cầu thẻ và việc dùng dữ liệu gói miễn phí để huấn luyện, kèm nguồn và ngày cho từng giá trị.
Những giới hạn nào gây ra lỗi 429?
Hãy biết rõ những con số bạn đang phải tính tới. Trên BroadNet Inference:
| Loại key | Request / phút | Đồng thời | Khác |
|---|---|---|---|
| Trả theo mức dùng | 30 | 4 | Ngân sách chi tiêu dùng chung |
| Key theo giờ | 120 | 1 stream | 300,000 token / phút |
| Phiên của gói không giới hạn | — | 1 request mỗi phiên | Không đo token |
Với LLM, số request đang chạy là quan trọng nhất. Một câu trả lời streaming giữ slot cho tới khi token cuối cùng về, nên một câu trả lời dài sẽ chiếm slot suốt thời gian model viết nó (BroadNet công bố tốc độ điển hình là khoảng 100 token mỗi giây). Gửi nhiều lệnh gọi song song hơn số 4 slot của key thì các lệnh dư sẽ bị 429, dù bạn chỉ gửi vài request trong phút đó. Đó là vấn đề đồng thời, và chỉ riêng backoff xử lý nó rất kém. Để tính số worker theo giới hạn trước khi chạy, hãy dùng công cụ tính giới hạn tốc độ LLM miễn phí. Với một job cố định gồm nhiều mục, công cụ lập kế hoạch job batch LLM chuyển cùng các giới hạn đó thành thời gian chạy. Các nhà cung cấp khác đếm theo cách khác (token mỗi phút, request mỗi ngày hoặc request đang chạy); bài giới hạn tốc độ API LLM theo nhà cung cấp so sánh 13 nhà cung cấp dựa trên tài liệu của chính họ.
Viết backoff có jitter như thế nào?
Exponential backoff thông thường chờ 1, 2, 4, 8 giây. Nếu một trăm worker bị chặn cùng một lúc, chúng sẽ cùng quay lại một lúc. Mô phỏng của AWS với 100 client tranh chấp cho thấy full jitter giảm số lệnh gọi xuống hơn một nửa và hoàn thành sớm hơn so với backoff không có jitter. Phiên bản đơn giản nhất, full jitter, chờ một khoảng thời gian ngẫu nhiên từ 0 đến mức trần lũy thừa:
import os, random, time
from openai import OpenAI, RateLimitError, APIStatusError, APIConnectionError
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)
RETRYABLE = {429, 500, 502, 503, 504}
def call_with_backoff(max_attempts=6, base=1.0, cap=60.0, **kwargs):
for attempt in range(max_attempts):
try:
return client.chat.completions.create(**kwargs)
except (RateLimitError, APIStatusError, APIConnectionError) as e:
status = getattr(e, "status_code", None)
if status is not None and status not in RETRYABLE:
raise # 400, 401, 403...: retrying will not help
if attempt == max_attempts - 1:
raise
retry_after = None
if getattr(e, "response", None) is not None:
retry_after = e.response.headers.get("retry-after")
wait = random.uniform(0, min(cap, base * 2 ** attempt))
if retry_after and retry_after.isdigit():
wait = max(wait, float(retry_after))
time.sleep(wait)
max_retries=0 tắt cơ chế retry riêng của SDK để bạn không retry hai lần. Nếu bạn hài lòng với hành vi có sẵn của SDK, làm ngược lại cũng được: bỏ vòng lặp của bạn đi và đặt max_retries=4 trên client, như hướng dẫn Python SDK trình bày. SDK Python và Node chính thức mặc định retry lỗi kết nối, 408, 409, 429 và 5xx hai lần.
Retry-After là một header chuẩn (RFC 9110), có thể chứa số giây hoặc một ngày giờ. Tài liệu của BroadNet không cam kết gửi header này, nên code coi nó là tùy chọn.
Làm sao ngăn lỗi 429 trước khi nó xảy ra?
Giới hạn số request đang chạy theo hạn mức của key. Trong Python, một asyncio.Semaphore làm việc này chỉ với một object và một khối async with. Đoạn code dùng 4 làm ví dụ; hãy đặt nó bằng giới hạn request đang chạy của key (4 với key trả theo mức dùng của BroadNet):
import asyncio, os
from openai import AsyncOpenAI
client = AsyncOpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
slots = asyncio.Semaphore(4) # match the key's in-flight limit
async def ask(prompt):
async with slots:
r = await client.chat.completions.create(
model="broadnet/gemma-4-26b-a4b",
messages=[{"role": "user", "content": prompt}],
)
return r.choices[0].message.content
async def main(prompts):
return await asyncio.gather(*(ask(p) for p in prompts))
results = asyncio.run(main(["Summarise A", "Summarise B", "Summarise C"]))
gather khởi động mọi tác vụ, nhưng chỉ có số tác vụ mà semaphore cho phép chạy cùng lúc. Phần còn lại chờ trong hàng đợi của semaphore. Trong Node, package p-limit làm điều tương tự, cũng với giá trị ví dụ là 4:
// ES module (top-level await). npm install openai p-limit
import OpenAI from "openai";
import pLimit from "p-limit";
const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY, maxRetries: 4 });
const limit = pLimit(4); // match the key's in-flight limit
async function ask(prompt) {
const r = await client.chat.completions.create({
model: "broadnet/gemma-4-26b-a4b",
messages: [{ role: "user", content: prompt }],
});
return r.choices[0].message.content;
}
const prompts = ["Summarise A", "Summarise B", "Summarise C"];
const results = await Promise.all(prompts.map((p) => limit(() => ask(p))));
Nếu cần thêm trần theo phút, hãy thêm một token bucket cấp một lượt mỗi 60 / rpm giây, trong đó rpm là giới hạn request mỗi phút của key (30 với key trả theo mức dùng của BroadNet).
Khi nào cần một hàng đợi thật sự?
Semaphore chỉ sống trong một process. Khi nhiều worker hoặc server dùng chung một key, giới hạn cũng bị dùng chung trong khi mỗi process chỉ thấy traffic của chính nó. Lúc đó:
- Đưa job vào một hàng đợi dùng chung (Redis, SQS, một bảng cơ sở dữ liệu).
- Chạy một số consumer cố định bằng đúng hạn mức request đang chạy của key.
- Gán ID cho mỗi job và lưu kết quả theo ID, để job được retry không bị chạy hai lần.
- Cho traffic tương tác và traffic batch đi qua các key riêng hoặc hàng đợi riêng, để batch tồn đọng không bao giờ chặn người dùng đang chờ câu trả lời.
Với job khối lượng lớn hàng nghìn mục mà không có Batch API, xem trình chạy batch có thể tiếp tục.
Những sai lầm retry nào biến lỗi 429 thành sự cố?
- Retry không giới hạn. Một vòng retry không có trần trong lúc sự cố kéo dài sẽ nhân tải của bạn lên nhiều lần, và khi tính phí theo token thì nhân cả hóa đơn.
- Retry mù quáng một stream đang dở. Nếu stream đã trả về token, retry là một lần inference mới và người dùng có thể thấy văn bản hai lần. Xem bài về streaming để biết cách phát hiện stream chưa hoàn chỉnh.
- Retry lỗi tài khoản. Lỗi 401 do hết hạn mức trả theo mức dùng hay 402 do không đủ số dư sẽ không tự hết.
Hãy ghi log mọi lần retry kèm trạng thái, thời gian chờ và header phản hồi X-Request-ID, header mà tài liệu của BroadNet yêu cầu bạn giữ lại để được hỗ trợ. Tỷ lệ retry tăng là cảnh báo sớm nhất rằng bạn cần thêm năng lực xử lý; bài ghi log mức dùng chỉ cách ghi lại.
BroadNet Inference phù hợp ở đâu?
Các giới hạn của BroadNet được công bố và đủ nhỏ để thiết kế quanh chúng: 4 request đồng thời trên một key trả theo mức dùng. Mức này hợp với ứng dụng và agent, nhưng quá chật cho một job khối lượng lớn muốn hàng trăm lệnh gọi song song trên một key. Với agent, gói không giới hạn không đo token và chạy một request tại một thời điểm cho mỗi phiên; bạn thêm phiên cho công việc song song, như mô tả trong bài chạy song song nhiều coding agent. Giới hạn hiện hành có trong tài liệu tham chiếu API.
