Lỗi Claude 529 overloaded_error — nguyên nhân và chiến lược retry

529 là lỗi Claude duy nhất không phải do mã của bạn gây ra: Anthropic đang quá tải. Bạn không thể sửa lỗi này — chỉ có thể xử lý đúng cách. Điều đó có nghĩa là retry kiên nhẫn với backoff, dùng mô hình dự phòng cho các luồng nhạy cảm với độ trễ, và tuyệt đối không tạo các đợt retry ngay lập tức làm sự cố trầm trọng hơn.

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, sự cố khu vực). Ảnh hưởng đến tất cả khách hàng cùng lúc.	Backoff kèm jitter; hãy kiểm tra trang trạng thái của Anthropic thay vì triển khai lại ứng dụng.
Đợt tăng tải của chính bạn trùng với năng lực hệ thống vốn đã căng thẳng.	Giãn các tác vụ batch; độ trễ mười phút thường là đủ.
Nhầm lẫn với 429: trong log, giới hạn tốc độ trông giống lỗi này, nhưng nguyên nhân hoàn toàn khác.	429 nghĩa là bạn đã vượt quá giới hạn của mình (máy chủ vẫn hoạt động bình thường); 529 nghĩa là máy chủ đang quá tải (hạn mức của bạn vẫn ổn). Chỉ 429 đi kèm gợi ý Retry-After.
Không định nghĩa phương án dự phòng, nên sự cố của nhà cung cấp truyền thẳng đến người dùng cuối.	Thiết lập chuỗi dự phòng — trong cùng một họ mô hình (Sonnet → Haiku), hành vi vẫn tương tự; giữa các nhà cung cấp (Claude → GPT), bạn vẫn có thể vượt qua một sự cố hoàn toàn.

Retry mà không làm sự cố trầm trọng hơn

Hãy xử lý 529 như 429 không có Retry-After: exponential backoff bắt đầu từ khoảng 2 giây, kèm jitter, giới hạn ở 30–60 giây, bỏ cuộc sau khoảng năm lần thử và đưa công việc vào hàng đợi. Jitter là phần quan trọng: nếu không có nó, tất cả client sẽ quay lại cùng lúc và kéo dài chính tình trạng quá tải mà chúng đang cố thoát khỏi.

Chuyển hướng thay vì ngừng hoạt động

Trên các luồng nhạy cảm với độ trễ, hãy định nghĩa một chuỗi dự phòng. Trên endpoint tương thích với OpenAI, đây chỉ là thay đổi một chuỗi ký tự — không cần SDK thứ hai, không cần tài khoản thứ hai:

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          # saturé — passer au palier suivant
    raise last

Chỉ sau đó mới kiểm tra mã của bạn

Nếu 529 chỉ xuất hiện với một loại yêu cầu duy nhất trong khi các lệnh gọi khác cùng lúc vẫn thành công, thì đó không phải sự cố diện rộng: hãy kiểm tra xem luồng này có gửi prompt lớn bất thường hoặc chạy trong vòng lặp quá sát nhau hay không. Ngược lại, nếu lỗi xuất hiện ở mọi lệnh gọi cùng lúc rồi tự biến mất, đó là vấn đề năng lực hệ thống — khi ấy cần retry và dự phòng, không phải tái cấu trúc.

Nếu bạn gọi qua Kunavo

Kunavo định tuyến Claude qua nhiều đường upstream, và danh mục đa mô hình biến failover giữa các nhà cung cấp thành việc thay đổi tên mô hình trên cùng một khóa và cùng một phương thức thanh toán — mẫu ở trên không cần tài khoản thứ hai. Các lỗi 529 vẫn đến được hệ thống của bạn sẽ không bao giờ bị tính phí. Năng lực hệ thống và giá là hai vấn đề riêng biệt; đối với vấn đề thứ hai, mức giá theo từng mô hình nằm trong bảng giá API Claude.

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 đề năng lực ở phía nhà cung cấp. Trách nhiệm duy nhất của bạn là không làm sự cố trầm trọng hơn (backoff, jitter) và có phương án dự phòng nếu sự cố kéo dài hơn ngân sách độ trễ của bạn.

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

429 nghĩa là bạn đã vượt quá giới hạn của mình, còn máy chủ vẫn hoạt động bình thường. 529 nghĩa là chính máy chủ đang quá tải, còn hạn mức của bạn vẫn ổn. Cả hai đều có thể retry; chỉ 429 cung cấp gợi ý Retry-After.

Một giai đoạn 529 kéo dài bao lâu?

Không thể dự đoán và cũng không thể đảm bảo — vì vậy câu trả lời đúng là backoff có giới hạn cộng với hàng đợi, không phải một khoảng thời gian được ghi cứng trong mã. Nếu luồng của bạn có ngân sách độ trễ, phương án dự phòng sẽ tiếp quản thay vì chờ.

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

Qua Kunavo thì không: yêu cầu kết thúc bằng lỗi sẽ không bị tính phí. Với hợp đồng trực tiếp, điều này phụ thuộc vào quy định thanh toán của nhà cung cấp liên quan.

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.

Lỗi 529 overloaded_error của API Claude — đây là gì và cách xử lý

Lỗi