Khi phát triển kịch bản tự động, bot hoặc tích hợp với luồng công việc, điều gây "đau đầu" nhất không phải là viết code, mà là việc đột nhiên gặp phải các lỗi như API key invalid, 401, 403 hoặc lỗi quá thời gian mạng. Đừng lo lắng, bài viết này sẽ cung cấp cho bạn một danh sách kiểm tra "có thể xác định vấn đề ngay lập tức", dựa trên trình tự xử lý sự cố của tôi, áp dụng chung cho ChatGPT, Claude và Gemini.
Xác định loại lỗi trước, đừng vội cài đặt lại
Nhiều người xem mọi vấn đề như "khóa sai" và kết quả là tốn công vô ích.
- 401: Khóa API không hợp lệ, thiếu khóa trong request, định dạng khóa sai, dự án chưa được kích hoạt API.
- 403: Quyền truy cập không đủ, bị hạn chế theo khu vực/chính sách kiểm soát rủi ro, bị chặn do chính sách hạn mức.
- 429: Bị giới hạn tốc độ (rate limit) hoặc đã sử dụng hết hạn mức (quota).
- Lỗi quá thời gian/ENOTFOUND: Vấn đề về mạng/DNS/proxy, không liên quan đến khóa API.
Nguyên nhân phổ biến gây lỗi khóa API không hợp lệ
Từ kinh nghiệm gỡ lỗi của các plugin thường đề cập đến "API key error" và các lỗi cấu hình phụ thuộc, tôi tổng hợp các nguyên nhân phổ biến nhất như sau:
- Sao chép thừa khoảng trắng hoặc dấu xuống dòng: Đặc biệt trong biến môi trường, thừa một khoảng trắng ở cuối có thể khiến bạn "đau đầu" không hiểu vì sao.
- Dùng nhầm khóa của nền tảng khác: Khóa của OpenAI, Anthropic và Google không thể dùng thay thế cho nhau. Đừng nhầm lẫn khóa của Gemini với cấu hình cho Claude.
- Sai tiêu đề yêu cầu (Request Header): Sai tiền tố Authorization, sai chữ hoa/chữ thường trong tên trường Header, thiếu từ khóa "Bearer".
- Dự án chưa bật tính phí/quyền truy cập: Khóa là thật, nhưng tài khoản chưa được cấp quyền truy cập API tương ứng, vẫn sẽ bị từ chối.
Lỗi 403 truy cập bị hạn chế: Tập trung kiểm tra khu vực và đầu ra mạng
Lỗi 403 rất khó chịu vì nó thường không cho bạn biết "chính xác điều gì không ổn". Kinh nghiệm của tôi là trước tiên kiểm tra IP đầu ra và quy tắc proxy, sau đó mới kiểm tra quyền tài khoản.
