Claude API 529 overloaded_error — lỗi này là gì và cách vượt qua

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

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)	Backoff có jitter; kiểm tra trang trạng thái của nhà cung cấp thay vì triển khai lại ứng dụng.
Đợt lưu lượng bùng nổ của bạn rơi đúng lúc có sự cố nhẹ	Phân tán các tác vụ theo lô; trì hoãn 10 phút thường sẽ giải quyết được.

Retry một cách có trách nhiệm

Xử lý 529 như 429-không-có-retry-after: exponential backoff bắt đầu khoảng 2 giây, jitter, giới hạn 30–60 giây, sau khoảng 5 lần thử thì từ bỏ và đưa công việc vào hàng đợi. Đoạn backoff từ hướng dẫn 429 của chúng tôi xử lý 529 trong cùng một nhánh.

Chuyển dự phòng thay vì để thất bại

Với các luồng nhạy cảm với độ trễ, hãy định nghĩa phương án dự phòng: cùng họ (Sonnet → Haiku) giữ hành vi gần tương tự; khác nhà cung cấp (Claude → GPT) chịu được sự cố toàn bộ nhà cung cấp. Trên điểm cuối tương thích OpenAI, đó chỉ là thay đổi một chuỗi:

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          # saturated — try the next tier
    raise last

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 việc chuyển dự phòng giữa các nhà cung cấp thành thay đổi chuỗi mô hình trên cùng một khóa và ví tiền — mẫu chuyển dự phòng ở trên không cần tài khoản thứ hai. Các lỗi 529 đến được với bạn vẫn không bao giờ bị tính phí. Dung lượng và giá là hai câu hỏi riêng; với câu hỏi thứ hai, đơn giá theo mô hình nằm trong bảng giá Anthropic 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 đề dung lượng ở phía nhà cung cấp. Trách nhiệm duy nhất của bạn là không khuếch đại sự cố (backoff, jitter) và có nơi để chuyển dự phòng nếu sự cố kéo dài quá ngân sách độ trễ của bạn.

529 so với 429 — khác nhau thế nào?

429 có nghĩa là bạn đã vượt quá giới hạn của mình (máy chủ vẫn ổn); 529 có nghĩa là chính máy chủ quá tải (quota của bạn vẫn ổn). Cả hai đều có thể retry; chỉ 429 đi kèm gợi ý retry-after.

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.