Claude Code báo 529 Overloaded: nguyên nhân, thiết lập thử lại và cách khắc phục

Wokey Team · 2026-09-24

Trả lời ngắn: lỗi 529 nghĩa là mô hình upstream đang hết công suất ngay lúc này ("overloaded"). Nó không liên quan gì đến số dư, hạn mức hay khóa API của bạn. Claude Code đã thử lại vài lần trước khi hiển thị lỗi. Cách khắc phục nhanh nhất là đổi mô hình bằng /model, vì công suất được tính theo từng mô hình. Nếu không vội, hãy đợi vài phút rồi gửi lại.

Thông báo lỗi chính xác

Trong Claude Code bạn sẽ thấy:

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

Tài liệu của Claude Code nêu ba điểm về lỗi này:

• Đây là sự cố công suất tạm thời, ảnh hưởng chung đến mọi người dùng.
• Claude Code đã thử lại vài lần trước khi hiển thị lỗi.
• Lỗi 529 không phải giới hạn sử dụng của bạn và không bị trừ vào hạn mức.

Khi bạn kết nối qua một gateway bằng ANTHROPIC_BASE_URL, câu cuối sẽ ghi tên host của gateway thay cho status.claude.com.

Lỗi 529 trên Wokey đến từ đâu

Wokey không bao giờ tự tạo ra lỗi 529; mã trạng thái này luôn đến từ mô hình upstream. Wokey xử lý nó theo ba bước:

1. Khi upstream báo quá tải (ví dụ overloaded_error của Anthropic), Wokey trước tiên thử lại yêu cầu của bạn trên một tuyến upstream khác cho cùng mô hình. Bạn không thấy bước này.

2. Chỉ khi lần thử lại cũng bị quá tải, Wokey mới chuyển tiếp mã trạng thái của upstream. Mã HTTP vẫn là 529. Nội dung phản hồi dùng định dạng lỗi chuẩn của Wokey, với nguyên văn thông báo của upstream trong message:

   {"error":{"code":"upstream_overloaded","message":"Overloaded","type":"invalid_request_error"}}
   

3. Nếu quá tải xảy ra sau khi phản hồi đã bắt đầu stream, nó sẽ đến dưới dạng sự kiện error trong luồng thay vì HTTP 529.

Vì vậy, một lỗi 529 qua Wokey nghĩa là nhiều tuyến upstream cho cùng mô hình đã quá tải cùng lúc, thường vào giờ cao điểm phía nhà cung cấp. Các phản hồi này không có header Retry-After; client của bạn thử lại theo lịch backoff riêng.

Phân biệt với các lỗi khác

Chỉ 529 và 503 mang nghĩa "upstream đang bận". Các mã còn lại cần bạn xử lý.

Cần làm gì

1. Đợi rồi gửi lại. Tình trạng quá tải thường hết trong vài phút, và cơ chế tự động thử lại của Claude Code đã xử lý được các đợt tăng đột biến ngắn.

2. Đổi mô hình bằng /model. Công suất được tính theo từng mô hình, nên khi Opus quá tải thì Sonnet thường vẫn hoạt động. Chạy /model trong phiên và chọn mô hình khác; không cần khởi động lại.

3. Với tác vụ dài chạy không người giám sát, hãy thử lại mạnh tay hơn. Thêm nội dung sau vào khối env của ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG": "1"
  }
}

• CLAUDE_CODE_RETRY_WATCHDOG=1 khiến Claude Code thử lại các lỗi 429 và 529 không giới hạn, với khoảng chờ giữa các lần tăng dần đến tối đa 5 phút. Phù hợp với các tác vụ để chạy qua đêm.
• Nếu chỉ cần thêm vài lần thử, hãy đặt CLAUDE_CODE_MAX_RETRIES. Mặc định là 10 và tối đa là 15.

4. Trong mã của bạn, hãy chừa chỗ để thử lại lỗi 529. Các SDK chính thức của Anthropic mặc định thử lại lỗi 5xx, bao gồm 529, hai lần. Với tác vụ hàng loạt, hãy tăng max_retries và thêm exponential backoff quanh lệnh gọi.

Gặp lỗi 529 trong Codex

Codex coi các lỗi 5xx, bao gồm 529, là có thể thử lại:

• Lớp HTTP mặc định thử lại 4 lần (request_max_retries của provider).
• Sau đó lớp stream thử lại thêm tối đa 5 lần (stream_max_retries).
• Nếu tất cả đều thất bại, thông báo lỗi bắt đầu bằng unexpected status 529, theo sau là nội dung phản hồi.

Nếu code trong nội dung đó là upstream_overloaded, đó là tình trạng quá tải upstream đã mô tả ở trên. Cách khắc phục cũng vậy: đợi, hoặc đổi mô hình trong config.toml. Để xem toàn bộ cách thiết lập Codex, hãy đọc hướng dẫn config.toml cho Codex.