API trả về mã trạng thái HTTP thông thường kèm một mã lỗi dành cho máy đọc. Hãy dựa vào mã trạng thái để quyết định bước tiếp theo. Bảng dưới đây theo tài liệu tham chiếu API của BroadNet.
| Mã trạng thái | Ý nghĩa | Cần làm gì |
|---|---|---|
| 400 / 422 | Request hoặc trường không hợp lệ | Sửa request trước |
| 401 | Thiếu key, key không hợp lệ hoặc hết hạn, ngân sách trả theo mức dùng bị chặn, hoặc đã dùng hết hạn mức | Kiểm tra trạng thái key và số dư tài khoản |
402 insufficient_balance |
Tài khoản không đủ tiền cho một giao dịch mua; body có kèm số dư và giá | Nạp tiền vào tài khoản rồi thử lại |
| 403 | Bị từ chối do chính sách về model, route hoặc IP | Sửa chỗ không khớp, ví dụ danh sách IP được phép |
| 409 | Xung đột với trạng thái tài khoản: mint_in_progress, key_limit_reached, credential_limit_reached, key_pending |
Chỉ thử lại mint_in_progress, với cùng request_id |
| 413 | Request quá lớn; file chép lời tối đa 26.214.400 byte | Giảm kích thước request |
| 429 | Chạm giới hạn tần suất, đồng thời, token mỗi phút hoặc chi tiêu | Đọc chi tiết trong phản hồi, tạm dừng rồi thử lại |
| 500 / 502 / 503 / 504 | Sự cố xử lý phía server | Thử lại với exponential backoff có giới hạn; khi mua key theo giờ, dùng lại cùng request_id |
Tài liệu của BroadNet khuyên kiểm tra mã trạng thái HTTP trước khi parse body JSON, sau đó mới đọc mã error dành cho máy đọc nếu có.
Những giới hạn nào gây ra lỗi 429?
Một key trả theo mức dùng cho phép 30 request mỗi phút và 4 request đang xử lý cùng lúc. Theo tài liệu của BroadNet, một key theo giờ được 120 request mỗi phút, một luồng và 300,000 token mỗi phút. Với gói không giới hạn, mỗi phiên xử lý một request tại một thời điểm. Để so sánh các giới hạn này với OpenAI, Anthropic, Groq và DeepSeek, hãy đọc giới hạn tần suất API LLM theo từng nhà cung cấp.
Thử lại với OpenAI SDK như thế nào?
Theo README trên GitHub, OpenAI Python SDK vốn đã tự thử lại lỗi kết nối và các phản hồi 408, 409, 429 và 5xx hai lần theo mặc định, với exponential backoff ngắn. Timeout mặc định là 10 phút. Hãy đặt rõ cả hai giá trị. Trong ví dụ dưới, max_retries bằng 0 sẽ tắt việc tự động thử lại; timeout tính bằng giây, hãy tăng lên cho những câu trả lời suy luận dài.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"],
max_retries=4, # 0 turns automatic retries off
timeout=120, # seconds; raise it for long reasoning answers
)
Tự viết backoff như thế nào?
Nếu bạn gọi API mà không dùng SDK, hãy giới hạn cả số lần thử lẫn thời gian chờ. Hàm dưới đây trả kết quả về ngay khi mã trạng thái không thuộc nhóm cần thử lại, tức là request đã thành công hoặc gặp lỗi cần sửa chứ không nên thử lại.
import random, time, requests
RETRY = {429, 500, 502, 503, 504}
def post_with_backoff(url, headers, body, tries=5):
for attempt in range(tries):
r = requests.post(url, headers=headers, json=body, timeout=120)
if r.status_code not in RETRY:
return r # success, or an error to fix rather than retry
time.sleep(min(30, 2 ** attempt) + random.random())
return r
Đừng bao giờ thử lại nguyên trạng các lỗi 400, 403, 413 hay 422: cùng một request sẽ thất bại theo cùng một cách. Mỗi lần thử lại một request chat là một lượt inference mới và bị tính phí lại nếu bạn trả theo mức dùng. Xem exponential backoff để biết mẫu chung.
Thử lại an toàn khi mua key theo giờ
POST /portal/keys/hourly nhận một request_id. Sau khi bị timeout, mất kết nối, gặp 409 mint_in_progress hoặc 5xx, hãy thử lại với cùng request_id. Một request_id được dùng lại không bao giờ tạo hay tính phí key thứ hai; lần gửi lại sẽ trả về already_issued: true cùng alias của key. Đừng tạo id mới khi chưa biết kết quả của lần đầu. Đọc thêm về idempotency key.
Xử lý sự cố
- 401 ngay sau khi nạp tiền. Trang tài khoản BroadNet hiển thị hạn mức được ghi nhận gần nhất và đánh dấu thay đổi về nạp tiền là đang cập nhật trong lúc áp dụng. Hãy tải lại trang và thử lại khi quá trình này đã xong.
- 429 dù chỉ gửi vài request mỗi phút. Nhiều khả năng bạn đang chạm giới hạn 4 request đồng thời, ví dụ khi chạy song song nhiều stream dài. Hãy dùng một worker pool nhỏ.
- 403 với một model nhưng model khác thì không. Chính sách của key không bao gồm model hoặc route đó. Ví dụ, key của gói dành cho
broadnet/deepseek-v4.1-flash, còn key theo giờ chỉ dùng được vớibroadnet/gemma-4-26b-a4b. - SDK tự thử lại và bạn bị tính phí hai lần. Một request chat được thử lại là một lượt inference mới. Hãy đặt
max_retries=0ở những chỗ mà một câu trả lời trùng lặp tốn kém hơn một lần thất bại.
Gửi gì cho bộ phận hỗ trợ
Hãy gửi giá trị header X-Request-ID, thời điểm theo UTC, route, mã trạng thái HTTP và alias của key. Tuyệt đối không gửi chính key. Hướng dẫn OpenAI Python SDK chỉ cách đọc header này.
