Lỗi Claude 529 (overloaded_error): nguyên nhân và cách xử lý

529 là lỗi Claude duy nhất không do mã của bạn gây ra. Tình trạng quá tải nằm ở phía Anthropic và bạn không thể khắc phục từ phía mình. Điều duy nhất có thể làm là «xử lý lỗi một cách hợp lý» — kiên trì thử lại với thời gian chờ tăng theo cấp số nhân, dùng mô hình dự phòng cho các luồng xử lý có yêu cầu nghiêm ngặt về độ trễ, và tránh liên tục thử lại ngay lập tức khiến sự cố trầm trọng hơn. Ba biện pháp này là toàn bộ cách ứng phó.

Lỗi

Phản hồi (HTTP 529)

{
  "type": "error",
  "error": { "type": "overloaded_error",
             "message": "Overloaded" }
}

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

Nguyên nhân	Cách khắc phục
Quá tải ở phía nhà cung cấp (ngày ra mắt mô hình mới, sự cố khu vực). Xảy ra đồng thời với mọi người dùng.	Chờ, áp dụng thời gian chờ giữa các lần thử lại kèm độ lệch ngẫu nhiên. Kiểm tra trang trạng thái của Anthropic thay vì triển khai lại ứng dụng.
Đợt gửi yêu cầu dồn dập của bạn trùng với lúc năng lực phục vụ vốn đã căng.	Phân tán việc xử lý theo lô ra nhiều thời điểm khác nhau. Hầu hết trường hợp chỉ cần lùi lại 10 phút là giải quyết được.
Nhầm lẫn với 429. Trong nhật ký, hai lỗi trông giống nhau, nhưng nguyên nhân hoàn toàn khác.	429 là khi bạn vượt quá giới hạn của mình (máy chủ vẫn bình thường), còn 529 là khi phía máy chủ quá tải (số dư và giới hạn vẫn bình thường). Chỉ 429 mới kèm Retry-After.
Chưa định nghĩa phương án dự phòng, nên vấn đề của nhà cung cấp truyền thẳng đến người dùng cuối.	Xác định trước thứ tự dự phòng. Nếu cùng dòng mô hình (Sonnet → Haiku) thì hành vi gần giống nhau, còn nếu chuyển sang nhà cung cấp khác (Claude → GPT) thì vượt qua được cả sự cố toàn hệ thống.

Thử lại mà không làm sự cố trầm trọng hơn

Hãy coi 529 là “429 không có Retry-After”. Dùng thời gian chờ tăng theo cấp số nhân, bắt đầu từ khoảng 2 giây, có độ lệch ngẫu nhiên, giới hạn trên là 30–60 giây; sau khoảng 5 lần thì bỏ cuộc và chuyển công việc vào hàng đợi. Phần phát huy tác dụng là độ lệch ngẫu nhiên. Nếu thiếu nó, mọi client sẽ quay lại vào cùng một thời điểm và kéo dài chính tình trạng quá tải mà bạn đang muốn thoát khỏi.

Chuyển hướng thay vì loại bỏ

Với các luồng xử lý có yêu cầu nghiêm ngặt về độ trễ, hãy chuẩn bị sẵn một chuỗi dự phòng. Nếu dùng endpoint tương thích OpenAI, thứ cần thay đổi chỉ là một chuỗi ký tự — không cần thêm SDK, cũng không cần thêm tài khoản:

failover.py

PREFERRED = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]

def complete(messages):
    last = None
    for model in PREFERRED:
        try:
            return client.chat.completions.create(
                model=model, messages=messages, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            last = e          # 過負荷 — 次の候補へ
    raise last

Nghi ngờ mã của chính mình sau cùng

Nếu chỉ một loại yêu cầu cụ thể nhận 529 trong khi các lệnh gọi khác cùng thời điểm vẫn thành công, đó không phải sự cố toàn hệ thống. Hãy kiểm tra xem luồng xử lý đó có đang gửi prompt lớn bất thường hay gửi yêu cầu liên tiếp trong một vòng lặp ngắn hay không. Ngược lại, nếu mọi lệnh gọi đồng loạt nhận 529 rồi sau một lúc tự lắng xuống, thì nguyên nhân là năng lực phục vụ. Khi đó, thứ cần chỉnh sửa là cơ chế thử lại và phương án dự phòng, chứ không phải tái cấu trúc mã.

Nếu bạn gọi qua Kunavo

Kunavo định tuyến Claude qua nhiều tuyến thượng nguồn; nhờ danh mục đa mô hình, việc chuyển sang mô hình dự phòng giữa các nhà cung cấp chỉ cần «đổi tên mô hình trong khi vẫn giữ nguyên khóa và số dư». Đoạn mã ở trên không cần tài khoản thứ hai. Các lỗi 529 vẫn nhận được dù đã áp dụng những biện pháp này sẽ không bị tính phí. Năng lực phục vụ và giá là hai vấn đề riêng biệt. Về vấn đề thứ hai, hãy xem đơn giá của từng mô hình trong bảng giá Claude API.

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

529 có phải lỗi của tôi không?

Không. Đây là vấn đề về năng lực phục vụ ở phía nhà cung cấp. Phía chúng ta chỉ có hai trách nhiệm — không làm sự cố trầm trọng hơn (áp dụng thời gian chờ giữa các lần thử lại và độ lệch ngẫu nhiên), và chuẩn bị sẵn tuyến chuyển hướng khi sự cố kéo dài quá thời gian trễ cho phép.

529 và 429 khác nhau thế nào?

429 là khi bạn vượt quá giới hạn của mình, còn bản thân máy chủ vẫn bình thường. 529 là khi máy chủ quá tải, còn giới hạn và số dư của bạn vẫn bình thường. Cả hai đều có thể thử lại, nhưng chỉ 429 mới kèm gợi ý Retry-After.

529 thường kéo dài bao lâu?

Không thể dự đoán, cũng không thể bảo đảm. Chính vì vậy, cách làm đúng là “thời gian chờ giữa các lần thử lại có giới hạn trên + hàng đợi”, chứ không phải viết cứng một thời gian chờ cố định vào mã. Nếu luồng xử lý đó có giới hạn độ trễ cho phép, phương án dự phòng sẽ tiếp quản thay vì chờ.

Các lệnh gọi thất bại vì 529 có bị tính phí không?

Qua Kunavo thì không bị tính phí. Các yêu cầu kết thúc bằng lỗi không thuộc diện tính phí. Nếu ký hợp đồng trực tiếp, việc tính phí tuân theo quy tắc của từng nhà cung cấp.

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 529 overloaded_error — ý nghĩa và cách xử lý đúng

Lỗi