Giải thích các lỗi API Claude: lỗi máy chủ 500, quá tải 529, giới hạn tốc độ 429, yêu cầu không hợp lệ 400 — và cách khắc phục từng lỗi

Mọi nhà phát triển sử dụng Claude API đều sẽ có lúc gặp lỗi. Một số lỗi do bạn gây ra (yêu cầu sai định dạng), một số thuộc về Anthropic (sự cố máy chủ), và một số liên quan đến kiến trúc (giới hạn tốc độ khi sử dụng ở cường độ cao). Hướng dẫn này trình bày mọi mã lỗi Claude API phổ biến cùng nguyên nhân thực tế, cách khắc phục cụ thể và logic thử lại sẵn sàng dùng trong môi trường vận hành thực tế. Hướng dẫn cũng giải thích cách định tuyến qua một cổng truy cập có nhiều tài khoản thượng nguồn có thể giảm tần suất gặp lỗi giới hạn tốc độ và quá tải.

Kiểm tra quyền truy cập và mô hình trước khi thử lại

Xác nhận quyền truy cập theo gói hoặc số dư của bạn đang hoạt động, kiểm tra nhóm khóa và sử dụng một mô hình được trả về cho khóa đó. Phản hồi liệt kê mô hình thành công là bước kiểm tra ban đầu; hãy xác minh bằng một yêu cầu tạo nội dung nhỏ trước khi chạy tác tử với tác vụ lớn hơn.

Sử dụng mô hình và nhóm khóa và thiết lập danh sách kiểm tra thiết lập tác tử để phân biệt vấn đề về quyền truy cập với vấn đề cấu hình công cụ và lỗi thượng nguồn.

"Lỗi máy chủ Claude": bạn thực sự đang gặp lỗi nào?

"Lỗi máy chủ Claude" là cụm từ mọi người nhập khi API ngừng phản hồi, nhưng con số trong thông báo mới quyết định cách xử lý. **500** nghĩa là API gặp lỗi nội bộ — hãy chờ, thử lại hoặc đổi mô hình. **529** nghĩa là mô hình đang quá tải với tất cả người dùng — xử lý tương tự, và lỗi sẽ tự hết. **429** nghĩa là bạn đã chạm giới hạn — hãy giảm tốc độ hoặc giảm số yêu cầu song song.

**400** nghĩa là bản thân yêu cầu đã bị từ chối — thử lại cùng yêu cầu đó sẽ tiếp tục thất bại. Hãy tìm mã lỗi của bạn bên dưới; mỗi phần đều cung cấp thông báo chính xác, nguyên nhân và cách khắc phục. Nếu bạn thấy lỗi trong Claude Code thay vì trong mã của mình, các hướng dẫn về lỗi Claude Code tại /claude-code/errors/ trình bày những thông báo riêng của CLI (hết thời gian chờ OAuth, "tiến trình đã kết thúc với mã 1", sử dụng công cụ đồng thời).

Lỗi 400 — Yêu cầu không hợp lệ

Lỗi 400 nghĩa là yêu cầu của bạn không hợp lệ về cấu trúc. Claude API đã từ chối yêu cầu trước cả khi thử tạo phản hồi. Phần nội dung lỗi chứa thông báo giải thích vấn đề — hãy luôn đọc kỹ. Các nguyên nhân phổ biến bao gồm: mảng messages trống hoặc sai định dạng, trường content có giá trị null thay vì chuỗi, max_tokens vượt giới hạn của mô hình, mã định danh mô hình không tồn tại, lời nhắc hệ thống sai định dạng hoặc định nghĩa công cụ có lỗi lược đồ.

Lỗi 400 thường gặp nhất đối với người dùng Claude Code là vượt quá độ dài ngữ cảnh. Khi lịch sử hội thoại vượt quá cửa sổ ngữ cảnh của mô hình (200K token đối với phần lớn mô hình Claude), API trả về 400 kèm thông báo đầu vào quá dài. Cách khắc phục là dùng /compact để tóm tắt lịch sử, xóa nội dung tệp lớn khỏi ngữ cảnh hoặc bắt đầu phiên mới. Đây không phải giới hạn tốc độ — mà là giới hạn cứng về kích thước yêu cầu.

Một lỗi 400 phổ biến khác là gửi tham số hoặc phiên bản mô hình không được hỗ trợ. Nếu gần đây bạn đã nâng cấp SDK hoặc thay đổi mã định danh mô hình, hãy kiểm tra lại để bảo đảm mọi trường trong yêu cầu đều khớp với đặc tả API hiện tại. ID mô hình phân biệt chữ hoa, chữ thường và phụ thuộc vào phiên bản — 'claude-opus-4-6' hợp lệ nhưng 'Claude-Opus-4.6' thì không. Khi không chắc chắn, hãy truy vấn điểm cuối /v1/models để xem chính xác những mã định danh mà nhà cung cấp chấp nhận.

Lỗi 400 - "Đầu vào quá dài đối với mô hình được yêu cầu"

Lỗi 400 cụ thể này nghĩa là yêu cầu của bạn (lời nhắc hệ thống + tin nhắn + mọi định nghĩa công cụ) vượt quá cửa sổ ngữ cảnh của mô hình. Đây không phải giới hạn tốc độ và thử lại sẽ không khắc phục được — cùng một nội dung yêu cầu sẽ luôn thất bại cho đến khi bạn giảm đầu vào hoặc chuyển sang mô hình có cửa sổ ngữ cảnh lớn hơn.

Ba cách khắc phục thực tế, theo thứ tự mức công sức cần bỏ ra: trước tiên, cắt bớt lịch sử hội thoại mà bạn gửi lại — phần lớn ứng dụng trò chuyện chỉ cần vài lượt gần nhất cùng bản tóm tắt được cập nhật liên tục, không cần toàn bộ bản ghi. Tiếp theo, đếm token trước khi gửi (điểm cuối đếm token được cung cấp miễn phí) và áp dụng ngân sách đầu vào cứng trong mã. Cuối cùng, nếu bạn thực sự cần toàn bộ ngữ cảnh — toàn bộ kho mã, tài liệu dài như sách — hãy chuyển sang mô hình có ngữ cảnh 1M như Fable 5, nơi yêu cầu đó nằm gọn trong giới hạn.

Một vấn đề dễ bị bỏ sót trong các công cụ tác tử: các phiên chạy lâu tích lũy kết quả công cụ và nội dung tệp cho đến khi chỉ thêm một lượt nữa cũng khiến yêu cầu vượt giới hạn. Nếu lỗi xuất hiện giữa phiên trong Claude Code hoặc một tác tử tương tự, hãy nén hoặc xóa ngữ cảnh phiên thay vì rút ngắn lời nhắc.

Lỗi 429 — "Đã đạt giới hạn tốc độ" / "Đã vượt tốc độ"

Cùng một tình trạng được diễn đạt theo hai cách. API trả về HTTP 429 kèm rate_limit_error; claude.ai và Claude Code hiển thị là "đã vượt tốc độ" hoặc "đã đạt giới hạn tốc độ". Dù bạn thấy thông báo nào, nguyên nhân vẫn giống nhau: tài khoản của bạn đã dùng hết hạn mức trong khoảng thời gian hiện tại và các yêu cầu bị từ chối cho đến khi hạn mức được đặt lại.

429 nghĩa là bạn đã vượt tốc độ yêu cầu được phép. Phản hồi có tiêu đề Retry-After cho biết bạn cần chờ bao nhiêu giây trước khi thử lại. Giới hạn tốc độ của Anthropic áp dụng trên nhiều tiêu chí: số yêu cầu mỗi phút (RPM), số token mỗi phút (TPM) và số token mỗi ngày (TPD). Chạm bất kỳ giới hạn nào trong số này đều gây ra 429. Thông báo lỗi thường cho biết giới hạn nào đã bị chạm.

Với người dùng Claude Code, giới hạn tốc độ là lỗi gây khó chịu nhất vì làm gián đoạn quy trình làm việc. Chỉ một nhà phát triển chạy Claude Code với các tác tử phụ cũng có thể dễ dàng chạm giới hạn RPM khi thực hiện thao tác song song, hoặc giới hạn TPM trong các phiên có tệp lớn trong ngữ cảnh. Các giới hạn khác nhau tùy theo cấp tài khoản — cấp thấp hơn có giới hạn nghiêm ngặt hơn, thường xuyên bị vượt khi sử dụng tác tử ở cường độ cao.

Cách xử lý đúng khi gặp 429 là chờ lùi theo cấp số nhân kèm độ trễ ngẫu nhiên. Chờ hết khoảng thời gian Retry-After, rồi thêm độ trễ ngẫu nhiên để tránh tình trạng nhiều máy khách đồng loạt gửi lại yêu cầu khi cùng chạm giới hạn. Một gateway như AI Prime Tech Unlimited giúp giảm lỗi 429 bằng cách định tuyến yêu cầu qua nhiều tài khoản phía thượng nguồn, qua đó tăng tổng hạn mức tốc độ khả dụng. Khi một tài khoản phía thượng nguồn bị giới hạn tốc độ, gateway sẽ định tuyến sang tài khoản khác.

Lỗi 500 — Lỗi máy chủ nội bộ

Lỗi 500 nghĩa là đã có sự cố ở phía máy chủ — không phải lỗi của bạn, cũng không phải vấn đề bạn có thể khắc phục bằng cách thay đổi yêu cầu. Đây là lỗi tạm thời: cùng một yêu cầu đã thất bại với 500 có khả năng sẽ thành công nếu bạn thử lại sau một khoảng chờ ngắn. Hạ tầng của Anthropic đôi khi trả về lỗi 500 trong quá trình triển khai, thay đổi năng lực phục vụ hoặc khi dịch vụ nội bộ bị gián đoạn.

Cách xử lý đúng đối với lỗi 500 là thử lại với thời gian chờ tăng dần. Chờ 1-2 giây rồi gửi lại đúng yêu cầu đó. Nếu vẫn thất bại, chờ 4 giây, rồi 8, đến tối đa khoảng 60 giây. Phần lớn lỗi 500 được giải quyết ngay trong lần thử lại đầu tiên. Nếu liên tục gặp lỗi 500 trong hơn vài phút, hãy kiểm tra trang trạng thái của Anthropic hoặc endpoint trạng thái của gateway để xem các sự cố đã được ghi nhận.

Đừng sửa đổi yêu cầu khi gặp 500 — vấn đề nằm ở phía máy chủ. Thay đổi prompt, giảm ngữ cảnh hoặc chuyển mô hình sẽ không giúp ích và chỉ làm mất thời gian phát triển để gỡ lỗi một vấn đề không thuộc về bạn. Những việc duy nhất cần làm là: thử lại, chờ lâu hơn nếu các lần thử lại thất bại và phát cảnh báo nếu lỗi kéo dài quá khoảng thời gian hợp lý (5-10 phút thất bại liên tục).

Lỗi 529 — "Máy chủ Claude đang quá tải" (overloaded_error)

Mã trạng thái 529 là mã riêng của Anthropic và có nghĩa là API đang có nhu cầu sử dụng cao — mô hình bạn yêu cầu tạm thời đã hết năng lực phục vụ. Khác với 429 (nghĩa là đã vượt giới hạn tốc độ YOUR), 529 nghĩa là SYSTEM đang quá tải bất kể giới hạn riêng của bạn. Bạn không làm gì sai; đơn giản là nhu cầu tại thời điểm đó vượt quá tài nguyên tính toán khả dụng.

Lỗi 529 thường gặp nhất trong giờ cao điểm (giờ làm việc tại Mỹ), ngay sau khi mô hình mới được phát hành (mọi người đồng thời thử mô hình mới) và trong những thời điểm lan truyền mạnh khi mức sử dụng tăng vọt trên toàn bộ khách hàng. Lỗi này ít gặp ở Sonnet và Haiku hơn Opus, vì Opus cần nhiều tài nguyên tính toán hơn cho mỗi yêu cầu và có giới hạn năng lực phục vụ chặt chẽ hơn.

Xử lý lỗi 529 với thời gian chờ tăng dần dài hơn so với lỗi 500. Bắt đầu bằng việc chờ 5-10 giây rồi tăng theo cấp số nhân. Nếu đang xây dựng hệ thống vận hành thực tế, hãy cân nhắc cơ chế chuyển sang mô hình dự phòng: khi Opus trả về 529, chuyển yêu cầu đó sang Sonnet. Một gateway có nhiều tài khoản phía thượng nguồn cũng có thể giúp ích — tình trạng quá tải có thể ảnh hưởng khác nhau đến các mức ưu tiên của từng tài khoản, giúp gateway có thêm lựa chọn định tuyến khi nhu cầu đạt đỉnh.

"Không có máy chủ thượng nguồn hoạt động tốt" — Lỗi hạ tầng, không phải lỗi Claude

"Không có máy chủ thượng nguồn hoạt động tốt" không phải thông báo do chính Claude API trả về. Đây là thông báo do bộ cân bằng tải hoặc proxy đầu vào (thường là Envoy) phát ra khi mọi phiên bản backend phía sau nó đều không khả dụng. Bạn sẽ thấy thông báo này trên claude.ai khi xảy ra sự cố gián đoạn, cũng như từ bất kỳ proxy hoặc gateway nào có nhóm kết nối thượng nguồn đã cạn hoặc không vượt qua kiểm tra tình trạng hoạt động.

Không có gì cần sửa trong mã của bạn. Hãy coi đây là lỗi tạm thời: kiểm tra status.anthropic.com, chờ và thử lại với thời gian chờ tăng theo cấp số nhân, giống hệt cách xử lý 529. Nếu lỗi kéo dài hơn vài phút trên endpoint chính thức, đó là sự cố gián đoạn dịch vụ; nếu lỗi đến từ gateway của bên thứ ba, gateway đó đã mất toàn bộ năng lực phục vụ phía thượng nguồn.

Đây là một trong những dạng sự cố mà gateway đa tài khoản được xây dựng để xử lý: khi một tài khoản phía thượng nguồn bị hạn chế tốc độ hoặc hoạt động không ổn định, yêu cầu sẽ được định tuyến sang tài khoản khác thay vì trả lỗi cho bạn.

Logic thử lại sẵn sàng cho môi trường vận hành thực tế

Logic thử lại tốt xử lý thống nhất mọi lỗi tạm thời (429, 500, 529) bằng thời gian chờ tăng theo cấp số nhân và độ trễ ngẫu nhiên, đồng thời coi các lỗi cố định (400, 401, 403) là không thể thử lại. Quy trình là: gửi yêu cầu, kiểm tra mã trạng thái, nếu có thể thử lại thì chờ với thời gian tăng dần và thử lại tối đa N lần, nếu không thể thử lại thì báo lỗi ngay. Số lần thử lại tối đa nên là 3-5 đối với phần lớn ứng dụng.

Độ trễ ngẫu nhiên ngăn các lần thử lại diễn ra đồng loạt. Nếu mười máy khách cùng chạm giới hạn tốc độ và đều thử lại sau đúng 2 giây, tất cả sẽ lại đồng thời thất bại. Thêm độ trễ ngẫu nhiên (nhân thời gian chờ với một hệ số ngẫu nhiên từ 0.5 đến 1.5) giúp phân tán các lần thử lại theo thời gian và cải thiện đáng kể tỷ lệ thành công. Mọi máy khách Claude API dùng trong môi trường vận hành thực tế đều nên có độ trễ ngẫu nhiên.

Đối với Claude Code và các quy trình làm việc dùng tác nhân, hãy triển khai cơ chế thử lại ở cấp máy khách HTTP để từng lệnh gọi công cụ và yêu cầu của tác nhân phụ tự động được hưởng lợi. SDK của Anthropic đã có logic thử lại cơ bản, nhưng bạn có thể muốn tùy chỉnh thời gian chờ hết hạn và số lần thử lại tối đa cho trường hợp sử dụng của mình. Nếu dùng AI Prime Tech Unlimited, gateway sẽ xử lý nội bộ việc thử lại phía thượng nguồn và định tuyến, qua đó giảm ngay từ đầu số lỗi mà máy khách của bạn gặp phải.

Gateway giảm các lỗi này như thế nào

Một gateway có kiến trúc tốt như AI Prime Tech Unlimited giảm tần suất lỗi theo nhiều cách. Đối với giới hạn tốc độ (429), gateway phân phối yêu cầu qua nhiều tài khoản API phía thượng nguồn, nên giới hạn tốc độ thực tế của bạn là tổng hạn mức của tất cả tài khoản phía thượng nguồn thay vì hạn mức của một tài khoản. Đối với lỗi quá tải (529), gateway có thể thử lại trên các tài khoản phía thượng nguồn khác có mức ưu tiên hoặc vị trí trong hàng đợi khác nhau.

Đối với lỗi máy chủ (500), gateway có thể tự động thử lại trước khi trả lỗi về máy khách của bạn — bạn nhận được phản hồi chậm hơn một chút thay vì lỗi. Đối với lỗi 400, gateway không thể giúp vì bản thân yêu cầu không hợp lệ, nhưng các gateway tốt cung cấp thông báo lỗi rõ ràng hơn, giúp bạn gỡ lỗi nhanh hơn so với phản hồi lỗi nguyên bản của Anthropic.

Kết quả đối với nhà phát triển là ít lỗi đến ứng dụng hơn, ít cần logic thử lại ở phía máy khách hơn và hiệu suất ổn định hơn trong giờ cao điểm. Điều này đặc biệt có giá trị với các phiên Claude Code, nơi lỗi giữa chừng có thể làm gián đoạn công việc, và với các ứng dụng vận hành thực tế, nơi tỷ lệ lỗi ảnh hưởng trực tiếp đến trải nghiệm người dùng. Mức phí cố định của gói không giới hạn có nghĩa là các lần thử lại và định tuyến lại này không khiến bạn mất thêm chi phí.

import anthropic
import time
import random

client = anthropic.Anthropic(
    api_key="YOUR_KEY",
    base_url="https://aiprimetech.io",
)

def call_with_retry(messages, model="claude-sonnet-4-5", max_retries=4):
    for attempt in range(max_retries + 1):
        try:
            return client.messages.create(
                model=model,
                max_tokens=4096,
                messages=messages,
            )
        except anthropic.RateLimitError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            print(f"Rate limited, waiting {wait:.1f}s...")
            time.sleep(wait)
        except anthropic.InternalServerError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            time.sleep(wait)
        except anthropic.BadRequestError:
            raise  # Don't retry 400s

# Usage:
resp = call_with_retry([{"role": "user", "content": "Hello"}])

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

AI Prime Tech là một cổng API độc lập. AI Prime Tech không liên kết với, không được Anthropic chứng thực và không phải là đại lý bán lại của Anthropic. Claude và các tên mô hình liên quan là nhãn hiệu của chủ sở hữu tương ứng.