Hướng dẫn khắc phục lỗi thường gặp của Claude API: Xử lý lỗi 401 Unauthorized và 429 Rate Limit

Khi sử dụng Claude API, nhà phát triển thường gặp lỗi 401 xác thực hoặc 429 giới hạn tốc độ, ảnh hưởng đến độ ổn định của dịch vụ. Bài viết này tổng hợp nguyên nhân và các bước sửa lỗi thực tế, giúp bạn nhanh chóng khôi phục cuộc gọi API.

Lỗi 401 Unauthorized: Kiểm tra khóa API và quyền truy cập

Mã lỗi 401 thường cho thấy khóa API không hợp lệ, đã hết hạn hoặc không được truyền đúng cách. Đầu tiên, hãy kiểm tra trường Authorization trong header, đảm bảo định dạng là Bearer YOUR_API_KEY, chú ý đến chữ hoa chữ thường và khoảng trắng ở cuối. Nếu khóa được nạp qua biến môi trường, hãy kiểm tra tên biến có bị sai chính tả hay không.

Trong một số trường hợp, khóa API bị hạn chế bởi chính sách cấp tổ chức, không thể gọi được một số mô hình cụ thể (ví dụ: claude-3-opus). Đăng nhập vào bảng điều khiển Anthropic để xem phạm vi quyền của khóa API, nếu cần hãy tạo lại khóa và liên kết với dự án mới.

Lỗi 429 Rate Limit: Kiểm soát tần suất yêu cầu hợp lý

Mã lỗi 429 cho biết số lượng yêu cầu hiện tại đã vượt quá hạn mức mỗi phút. Claude API có giới hạn về số lượng yêu cầu và số token, bạn có thể dự đoán hạn mức còn lại thông qua header phản hồi X-RateLimit-Remaining. Nên triển khai cơ chế thử lại với back-off theo cấp số nhân trong mã: chờ 1 giây lần đầu, nếu thất bại thì nhân đôi lên tối đa 30 giây.

Nếu thường xuyên gặp lỗi 429, bạn có thể yêu cầu nâng cấp gói hạn mức, hoặc giảm tần suất yêu cầu bằng cách gộp nhiều yêu cầu thành một batch. Tránh gửi đồng thời quá nhiều yêu cầu ngắn trong thời gian ngắn.

Lỗi máy chủ 500 và chiến lược thử lại

Mã lỗi 500 cho thấy dịch vụ phía Claude gặp sự cố tạm thời, thường do tải cao hoặc lỗi nội bộ. Loại lỗi này thường là nhất thời, chỉ cần đợi vài giây là có thể khôi phục. Nên thử lại tối đa ba lần, cách nhau 2-4 giây, và sử dụng tham số max_retries để tránh vòng lặp vô hạn.

Đồng thời kiểm tra các tham số trong body yêu cầu có hợp lệ hay không – giá trị max_tokens quá lớn hoặc body message sai định dạng đôi khi cũng gây ra lỗi 500. Sử dụng SDK Python chính thức hoặc kiểm tra JSON Schema trước khi gọi có thể giảm thiểu vấn đề này.