Claude API timeout request và “streaming is strongly recommended”

Thông thường có ba timeout giữa bạn và mô hình — timeout của SDK, của bên trung gian và quy tắc riêng của nhà cung cấp đối với các lệnh gọi không streaming dài — và timeout ngắn nhất sẽ thắng. Chỉ tăng timeout của SDK là lý do vấn đề vẫn tiếp diễn sau khi bạn tưởng rằng đã sửa xong.

Lỗi

hai dạng

# Rejected before generating, for a long non-streaming request:
{"type":"error","error":{"type":"invalid_request_error",
 "message":"Streaming is strongly recommended for operations that may take
 longer than 10 minutes."}}

# Or the client-side companion, with no response at all:
APITimeoutError: Request timed out.

Tổng quan nguyên nhân và cách khắc phục

Nguyên nhân	Cách khắc phục
Một lần tạo dài không streaming	Hãy stream. Các phần hoàn tất dài được kỳ vọng sẽ được stream, không phải chờ đợi.
Timeout của client SDK ngắn hơn thời gian tạo	Tăng nó — nhưng cũng phải tăng giới hạn của bên trung gian, nếu không sẽ không có gì thay đổi.
Proxy, load balancer hoặc hàm serverless giới hạn request	Tìm giới hạn ngắn nhất trong chuỗi; đó là giới hạn bạn đang gặp phải.
Kết nối được chấp nhận nhưng sau đó không có phản hồi	Đây là tình trạng treo, không phải phản hồi chậm. Hãy giới hạn riêng thời gian đến byte đầu tiên.

Stream mọi thứ có thể chạy quá vài phút

Ngoài việc tránh giới hạn, streaming còn cung cấp tín hiệu hoạt động: token đến nghĩa là mô hình vẫn đang làm việc, nên có thể phân biệt tình trạng treo với tiến trình chậm. Với một lệnh gọi blocking duy nhất, hai tình trạng này trông giống hệt nhau cho đến khi timeout kích hoạt.

Tăng mọi timeout trong chuỗi, không chỉ timeout của SDK

Hầu hết mọi người chỉ thay đổi client rồi dừng lại. Nếu reverse proxy hoặc nền tảng serverless giới hạn request thấp hơn timeout mới của client, giới hạn đó vẫn thắng và triệu chứng không thay đổi.

client.py

from anthropic import Anthropic

# Client timeout is only one of the limits in play.
client = Anthropic(api_key=KEY, timeout=600.0)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8192,
    messages=[{"role": "user", "content": prompt}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Giới hạn riêng thời gian đến byte đầu tiên và tổng thời lượng

Đây là hai lỗi khác nhau cần hai biện pháp khắc phục khác nhau. Deadline byte đầu tiên ngắn sẽ nhanh chóng phát hiện kết nối chết; deadline tổng rộng rãi cho phép một lần tạo thực sự dài hoàn tất. Một timeout kết hợp không thể làm cả hai việc.

Đảm bảo retry an toàn trước khi thêm chúng

Một request đã hết thời gian ở phía bạn có thể đã hoàn tất ở upstream. Nếu công việc có side effect hoặc bạn bị tính phí theo mỗi lần gọi, hãy thêm idempotency ở tầng của bạn trước khi thêm vòng lặp retry.

Nếu bạn gọi qua Kunavo

Kunavo công bố các con số riêng thay vì để bạn tự phát hiện: Kunavo chờ tối đa 240 giây cho response headers từ upstream, và một câu trả lời không streaming thường chỉ gửi headers sau khi hoàn tất, vì vậy lệnh gọi không streaming cần lâu hơn thời gian đó sẽ không hoàn tất qua gateway — hãy stream. Giới hạn 240 giây chỉ áp dụng cho thời gian đến headers và được giải phóng ngay khi headers đến, nên không bao giờ cắt một stream dài; gateway không có giới hạn nào khác đối với độ dài stream. Điều thực sự kết thúc stream là sự im lặng: 300 giây không có byte nào từ upstream hoặc 600 giây không có byte nào trên kết nối đến bạn. Các route hình ảnh, video và âm nhạc đồng bộ giữ kết nối tối đa 540 giây trong khi render hoàn tất, nằm trong cửa sổ 600 giây đó, vì quá trình render thực sự có thể mất vài phút. Request hết thời gian trước headers được tính là lỗi kênh, được retry trên kênh tiếp theo của mô hình nếu có cấu hình, và được ghi nhận với chi phí bằng 0.

Câu hỏi thường gặp

Request hết thời gian có bị tính phí không?

Trên Kunavo thì không — các request thất bại được ghi nhận với chi phí bằng 0. Nếu thanh toán trực tiếp cho nhà cung cấp, việc có bị tính phí hay không phụ thuộc vào việc quá trình tạo có thực sự diễn ra hay không.

Tại sao streaming tránh được giới hạn?

Phản hồi bắt đầu trong vài giây và kết nối luôn bận, nên không có khoảng im lặng liên tục nào đủ dài để kích hoạt timeout.

Timeout của client nên đặt bao lâu?

Dài hơn lần tạo thực tế tồi tệ nhất, kết hợp với một deadline byte đầu tiên riêng và ngắn. Một timeout kết hợp dài sẽ biến mọi tình trạng treo thành quá trình chờ nhiều phút.

Hướng dẫn liên quan

Thông tin chi tiết hơn về ý nghĩa lỗi có trong tài liệu tham chiếu lỗi; bạn chỉ mất một phút để lấy khóa qua đăng ký và hướng dẫn xác thực.

Claude API timeout request và “streaming is strongly recommended” — quy tắc 10 phút

Lỗi