Giải mã lỗi Claude API: xử lý 401/403/404/429/529 từ A đến Z
Giải mã lỗi Claude API: xử lý 401/403/404/429/529 từ A đến Z
Ba giờ sáng, pipeline đỏ toàn màn hình và log chỉ hiện một dòng: authentication_error. Đây là cảnh quen thuộc của mọi ai tích hợp Claude API. Tin tốt: API error rất chính xác — mỗi mã báo đúng chỗ hỏng. Bài viết này mổ xẻ năm mã lỗi phổ biến nhất: ý nghĩa, nguyên nhân thường gặp, cách sửa cụ thể, và một thứ tự kiểm tra cố định để chấm dứt việc đoán mò.
Error response trông như thế nào
Định nghĩa: API phong cách Anthropic trả JSON có envelope nhất quán khi lỗi: type tầng trên là error, error.type bên trong là phân loại máy đọc được (ví dụ authentication_error), error.message là giải thích cho người. Khi phân tích lỗi, luôn đọc error.type trước — nó xác định điểm hỏng chính xác hơn mã trạng thái riêng lẻ.
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "invalid x-api-key"
}
}
Một chi tiết từ test thực tế
Qua gateway, lỗi xác thực có thể bị chặn trước khi forward và body khi đó có thể là text ngắn (ví dụ 401 chỉ với Invalid token) thay vì JSON đầy đủ. Cách kiểm tra: retry một lần với key đúng. Nếu thông qua thì endpoint và path bình thường, lỗi trước đó nằm ở tầng key.
401 authentication_error: tầng key
Nguyên nhân: request không kèm key, key sai chính tả, key đã bị thu hồi — hoặc biến môi trường cũ đè lên cấu hình.
Cách sửa: Xác nhận key được gửi qua header x-api-key (chuẩn Anthropic) và không thừa khoảng trắng → chạy echo $ANTHROPIC_API_KEY kiểm tra giá trị trong shell hiện tại → tạo key mới trong console để đối chiếu — nếu key mới chạy được thì key cũ đã chết thật.
Trường hợp 401 phổ biến nhất
Chỉ cần unset một biến môi trường cũ đã giải quyết hơn nửa số 401. Biến export trong shell luôn thắng file cấu hình — khi cả hai tồn tại, shell thắng.
403 permission_error: tầng quyền
Nguyên nhân: key hợp lệ nhưng không có quyền truy cập tài nguyên — phổ biến nhất là key bị giới hạn nhóm mô hình, hoặc tài khoản bị tạm ngưng.
Cách sửa: 403 khác 401 một điểm — "key đúng nhưng thiếu quyền". Kiểm tra trạng thái tài khoản trước, rồi xác nhận mô hình đích có trong phạm vi của key. Qua gateway thì kiểm tra gateway có giới hạn mô hình đó không; đổi mô hình hoặc chỉnh trong console khi cần.
404 not_found_error: path và model ID
Nguyên nhân: hai khả năng — sai đường dẫn, hoặc model ID không tồn tại.
Kiểm tra path: endpoint chính thức là https://api.anthropic.com/v1/messages; qua EXAIV là https://exaiv.com/api/ai/v1/anthropic/v1/messages. Lỗi thường gặp nhất là áp path kiểu OpenAI (/v1/chat/completions) vào protocol Anthropic, hoặc thiếu đoạn /v1.
Kiểm tra model name: model: "claude-opus-4-8" lệch một ký tự với ID thật là 404 ngay. Danh sách khả dụng theo phía endpoint — đầy đủ ở trang mô hình.
429 rate_limit_error: tầng giới hạn
Nguyên nhân: tần suất hoặc concurrency vượt hạn mức. Đây không phải sự cố — đó là hệ thống nói "giảm tốc bây giờ".
Cách sửa: Đọc retry-after trong response và chờ theo → triển khai exponential backoff: 1 giây, rồi 2, 4, 8 với jitter tránh các client dồn cùng lúc → dài hạn: hạ concurrency, gộp request, hoặc thêm token-bucket phía client
429 khác 529 chỗ nào
429 là "bạn đang quá nhanh" — lỗi thuộc phía caller, sửa bằng backoff. 529 là "phía thượng nguồn đang quá tải" — không thuộc caller, sửa bằng chờ. Cả hai đều không giải quyết bằng retry ngay lập tức.
529 overloaded_error: thượng nguồn quá tải
Nguyên nhân: dịch vụ thượng nguồn tạm thời quá tải, không nhận request mới trong giới hạn thời gian. Đây là mã riêng của Claude (semantic của OpenAI không có giá trị tương ứng) và được gateway truyền nguyên xi.
Cách sửa: exponential backoff thường hồi phục trong vài giây đến vài chục giây. Với pipeline cần tính liên tục cao, cấu hình một mô hình dự phòng để giảm tải — một trong những lợi ích cốt lõi của gateway: đổi mô hình chỉ là đổi một chuỗi, không cần key mới hay làm lại xác thực.
Các mã khác xem nhanh
| Code | error.type | Ý nghĩa | Xử lý |
|---|---|---|---|
| 400 | invalid_request_error | Body hoặc tham số sai | Đọc message; thường thiếu max_tokens hoặc messages sai cấu trúc |
| 413 | request_too_large | Body quá giới hạn | Cắt gọn context hoặc tách tài liệu |
| 500 | api_error | Lỗi nội bộ thượng nguồn | Backoff và retry; chỉ điều tra nếu kéo dài |
Thứ tự kiểm tra: mỗi lần một tầng
| Tầng | Kiểm tra | Công cụ |
|---|---|---|
| ① Key | Giá trị trong shell hiện tại, đã thu hồi chưa | echo $ANTHROPIC_API_KEY |
| ② URL | Đường dẫn đủ (/v1) chưa | Đối chiếu mục 404 ở trên |
| ③ Model ID | So từng ký tự với danh sách | Trang mô hình |
| ④ Rate/overload | Trạng thái 429/529 | Backoff và retry |
| ⑤ Network | Proxy, firewall | Thử mạng khác |
Một thói quen tiết kiệm thời gian nhất: bấm thẳng endpoint bằng curl trước khi đụng code ứng dụng. Nếu curl được mà code không được, lỗi nằm ở tầng client của bạn. Nếu curl cũng lỗi, đi theo bảng trên — cách này rút thời gian debug trung bình từ nửa giờ xuống dưới năm phút.
Bọc một lần: request helper có retry
Thay vì rải logic retry khắp các điểm gọi, hãy bọc endpoint một lần để mọi tính năng thừa hưởng. Một helper tốt làm bốn việc theo thứ tự: gửi với key hiện tại và URL đầy đủ; phân loại thất bại theo error.type (authentication/permission không retry, rate và overload có retry); áp exponential backoff với jitter chỉ cho nhóm retry được đến giới hạn số lần; và báo lỗi cuối kèm model ID và số lần đã thử để log tự giải thích.
Các nhóm áp dụng pattern này ghi nhận lợi ích thứ cấp: khi xuất hiện một loại lỗi mới ở thượng nguồn, bảng phân loại nằm đúng một chỗ nên bản vá lan đến mọi điểm gọi cùng lúc. Chính helper đó cũng là nơi tự nhiên cho timeout budget theo môi trường — ngắn cho đường tương tác, dài cho batch — mà không chạm lại vào các điểm gọi.
Giám sát: biến lỗi thành dashboard
Đếm lỗi theo error.type theo thời gian biến bài viết này thành dashboard vận hành. Ba chuỗi là đủ cho đa số nhóm: lỗi xác thực (phải bằng phẳng — bất kỳ đột biến nào cũng nghĩa là có key lộ hoặc được luân chuyển ở đâu đó), lỗi rate-limit (đường cong hoạch định năng lực của bạn), và 529/500 (sức khỏe thượng nguồn từ góc nhìn của bạn). Cảnh báo với chuỗi thứ nhất, dự báo với chuỗi thứ hai, và chỉ gọi người cho chuỗi thứ ba hỏng kéo dài.
Một chi tiết khi đi qua gateway: các lần từ chối auth của gateway hiện như 401 text ngắn chứ không phải JSON envelope, nên hãy parse phòng thủ — coi mọi non-2xx là sự kiện lỗi và phân loại theo hình dạng body, không theo cấu trúc giả định. Điều này giữ dashboard trung thực trên cả đường trực tiếp lẫn đường gateway.