Lỗi Gặp Phải
cohere.errors.too_many_requests_error.TooManyRequestsError: status_code: 429, body: You are using a Trial key, which is limited to 10 API calls / minute. Upgrade to a Production key to increase your rate limit.
Mười lần gọi mỗi phút. Đó là giới hạn cứng của Cohere Trial key, và SDK sẽ ném ra TooManyRequestsError ngay khi bạn vượt qua ngưỡng đó — không tự động retry, không có thời gian ân hạn, chỉ là một lỗi 429.
Nguyên Nhân
Cohere Trial key giới hạn bạn ở đúng 10 lần gọi API mỗi phút. Lần gọi thứ mười một sẽ nhận về HTTP 429 ngay lập tức. Các nguyên nhân thường gặp:
- Lặp qua danh sách đầu vào và gọi
co.embed()hoặcco.chat()mà không có độ trễ nào - Các lần gọi async song song với
asynciođược kích hoạt cùng một lúc - Chạy script nhiều lần liên tiếp trong quá trình phát triển
- Xử lý hàng loạt gửi tất cả các mục trong một vòng lặp liên tục
Cách Sửa Từng Bước
Cách 1 — Thêm sleep đơn giản giữa các lần gọi (sửa nhanh nhất)
Danh sách nhỏ, không vội? Thêm độ trễ 6 giây giữa các lần gọi. Phép tính này cho ra đúng 10 lần gọi mỗi phút — chạm đúng giới hạn của Trial key.
import cohere
import time
co = cohere.ClientV2("YOUR_API_KEY")
texts = ["text one", "text two", "text three"] # dữ liệu đầu vào của bạn
for text in texts:
response = co.embed(
texts=[text],
model="embed-english-v3.0",
input_type="search_document",
)
print(response.embeddings)
time.sleep(6) # 10 calls/min = 1 lần gọi mỗi 6 giây
Cách 2 — Retry với exponential backoff (khuyến nghị cho code gần production)
Thay vì để lỗi 429 làm crash script, hãy bắt lỗi và retry với thời gian chờ tăng dần. Bắt đầu từ 10 giây và nhân đôi mỗi lần thử: 10s → 20s → 40s → 80s → 160s.
import cohere
import time
from cohere.errors import TooManyRequestsError
co = cohere.ClientV2("YOUR_API_KEY")
def embed_with_retry(text: str, max_retries: int = 5) -> list:
wait = 10 # giây
for attempt in range(max_retries):
try:
response = co.embed(
texts=[text],
model="embed-english-v3.0",
input_type="search_document",
)
return response.embeddings[0]
except TooManyRequestsError:
if attempt == max_retries - 1:
raise
print(f"Rate limited. Waiting {wait}s before retry {attempt + 1}/{max_retries}...")
time.sleep(wait)
wait *= 2 # exponential backoff: 10s → 20s → 40s
return []
# Sử dụng
result = embed_with_retry("Hello, world")
print(result)
Cách 3 — Gộp đầu vào vào một lần gọi duy nhất
Đây là đòn bẩy lớn nhất bạn có thể dùng: endpoint embed chấp nhận toàn bộ danh sách văn bản trong một lần gọi. Truyền 50 văn bản vào một lần gọi co.embed() duy nhất tiêu tốn cùng 1 đơn vị quota như khi chỉ truyền 1 văn bản. Hãy gửi tất cả cùng lúc thay vì lặp từng mục một.
import cohere
co = cohere.ClientV2("YOUR_API_KEY")
texts = [
"First document to embed",
"Second document to embed",
"Third document to embed",
# ... lên đến hàng trăm văn bản trong một lần gọi
]
response = co.embed(
texts=texts,
model="embed-english-v3.0",
input_type="search_document",
)
for i, embedding in enumerate(response.embeddings):
print(f"Text {i}: {len(embedding)} dimensions")
Mỗi lần gọi co.embed() được tính là một lần gọi API bất kể bạn truyền vào bao nhiêu văn bản (trong giới hạn token). Nghĩa là 100 văn bản chỉ tốn 1 đơn vị quota thay vì 100. Hãy dùng cách này trước khi nghĩ đến sleep hay retry.
Cách 4 — Dùng token bucket / rate limiter
Đang chạy code async hoặc pipeline phức tạp hơn? Thư viện ratelimit cho phép bạn khai báo giới hạn một lần dưới dạng decorator và không cần lo nữa.
pip install ratelimit
import cohere
from ratelimit import limits, sleep_and_retry
co = cohere.ClientV2("YOUR_API_KEY")
CALLS_PER_MINUTE = 9 # giữ dưới 10 để có khoảng đệm an toàn
ONE_MINUTE = 60
@sleep_and_retry
@limits(calls=CALLS_PER_MINUTE, period=ONE_MINUTE)
def rate_limited_chat(message: str) -> str:
response = co.chat(
model="command-r-plus",
messages=[{"role": "user", "content": message}],
)
return response.message.content[0].text
# Giờ bạn có thể gọi hàm này trong vòng lặp mà không lo bị 429
for msg in ["What is Python?", "Explain APIs", "What is embeddings?"]:
print(rate_limited_chat(msg))
Cách 5 — Nâng cấp lên Production key
Cần thông lượng thực sự? Trial key sẽ không đáp ứng được. Truy cập dashboard.cohere.com → API Keys → tạo Production key. Production key hỗ trợ hàng nghìn lần gọi mỗi phút tùy theo gói của bạn — bắt buộc phải có cho bất kỳ thứ gì ngoài phạm vi kiểm thử nội bộ.
Xác Nhận Đã Sửa Xong
Dán đoạn smoke test này để kiểm tra xem cách sửa của bạn có thực sự hoạt động không. Nó gửi 12 lần gọi — vượt hai lần so với giới hạn mỗi phút — với khoảng cách 6 giây giữa mỗi lần:
# Smoke test — 12 lần gọi ở tốc độ 10/phút để kiểm tra rate limiter
import cohere
import time
from cohere.errors import TooManyRequestsError
co = cohere.ClientV2("YOUR_API_KEY")
success = 0
for i in range(12):
try:
co.embed(
texts=[f"test text {i}"],
model="embed-english-v3.0",
input_type="search_document",
)
success += 1
time.sleep(6) # khoảng cách 6s = 10 lần gọi/phút
except TooManyRequestsError as e:
print(f"Still rate limited at call {i}: {e}")
break
print(f"{success}/12 calls succeeded")
Khi thấy 12/12 calls succeeded nghĩa là bạn đã xử lý xong.
Mẹo Hay
- Kiểm tra loại key trước: Vào
dashboard.cohere.com→ API Keys. Trial key được gắn nhãn "Trial". Nếu key của bạn đã hiển thị "Production" mà vẫn bị 429, có nguyên nhân khác đang gây ra giới hạn này. - Gộp batch trước khi dùng sleep: Luôn thử gộp nhiều văn bản vào một lần gọi
co.embed()trước khi dùngtime.sleep(). Một lần gọi với 100 văn bản hiệu quả hơn nhiều so với 100 lần gọi với mỗi lần một văn bản. - Nhắm 9 lần gọi/phút, không phải 10: Để dư một lần gọi làm khoảng đệm, phòng trường hợp lệch đồng hồ và các request nền mà code của bạn có thể kích hoạt ngầm.
- Ghi log thời gian chờ trong lúc phát triển: In ra thông báo trước mỗi lần
time.sleep(). Các vòng lặp vô tình sẽ lộ ra ngay — thay vì script lặng lẽ treo máy, bạn sẽ thấy chính xác khi nào nó đang tự điều tiết. - Xem lại xem bạn có thực sự cần chat không: Các endpoint rerank và chat tốn nhiều quota hơn mỗi lần gọi. Nếu bạn đang chạm giới hạn, hãy xem liệu batch embeddings có thể thay thế những gì bạn đang làm không — chúng xử lý nhiều văn bản trên mỗi đơn vị quota.