Lỗi và khắc phục sự cố
Xác định vấn đề gọi API theo nguồn lỗi và trạng thái HTTP, rồi chọn cách khôi phục an toàn.
Khi yêu cầu API thất bại, lưu mã trạng thái HTTP và thông tin lỗi đã che dữ liệu nhạy cảm trước, rồi xác định vấn đề đến từ yêu cầu, xác thực, mô hình hay máy chủ. Không liên tục thử lại cùng yêu cầu khi chưa xác định nguyên nhân.
Bảo vệ thông tin xác thực và dữ liệu khách hàng trước
Không đưa API Key đầy đủ, Header Authorization hoặc x-api-key, Cookie, mật khẩu, Prompt đầy đủ, tệp khách hàng hay thông tin nhạy cảm khác vào hồ sơ khắc phục sự cố.
Xác định nguồn lỗi trước
| Nguồn lỗi | Biểu hiện phổ biến | Hành động đề xuất |
|---|---|---|
| Nội dung yêu cầu | JSON không hợp lệ, thiếu trường, sai kiểu tham số hoặc định dạng tệp không đáp ứng yêu cầu | Sửa yêu cầu theo thông tin lỗi; không thử lại nguyên yêu cầu |
| Xác thực và quyền | API Key thiếu, không hợp lệ hoặc không có quyền truy cập mô hình mục tiêu | Kiểm tra Base URL, Header xác thực theo giao thức, trạng thái Key và quyền mô hình |
| Mô hình và tài nguyên | ID mô hình, ID tác vụ hoặc đường dẫn yêu cầu không tồn tại | Sao chép lại ID từ danh mục mô hình và kiểm tra tài khoản sở hữu tài nguyên |
| Nền tảng hoặc thượng nguồn | Dịch vụ tạm thời không khả dụng, xử lý quá thời gian chờ hoặc thượng nguồn trả lỗi | Lưu thông tin chẩn đoán và thử lại có giới hạn; dừng yêu cầu nếu tiếp tục thất bại |
| Tác vụ bất đồng bộ | Tác vụ thất bại sau khi gửi thành công, xử lý quá lâu hoặc kết quả không khả dụng | Truy vấn trạng thái tác vụ gốc trước để tránh tạo tác vụ trùng lặp |
Một lần thất bại có thể chứa nhiều dấu hiệu. Ví dụ, 404 có thể do endpoint viết sai hoặc mô hình hay tác vụ không tồn tại; cần đánh giá cùng URL yêu cầu cuối cùng và nội dung lỗi.
Tra cứu nhanh trạng thái HTTP
| Trạng thái HTTP | Ý nghĩa phổ biến | Cách khôi phục đề xuất |
|---|---|---|
400 | Định dạng yêu cầu, tham số hoặc nội dung đầu vào sai | Sửa yêu cầu rồi gửi lại |
401 | API Key thiếu, không hợp lệ hoặc Header xác thực không đáp ứng yêu cầu API | Kiểm tra cách xác thực của giao thức; tạo và thay Key mới khi cần |
403 | Phạm vi sử dụng của tài khoản, Key hoặc mô hình không đáp ứng yêu cầu | Kiểm tra trạng thái tài khoản, giới hạn token truy cập và quyền mô hình |
404 | Base URL, endpoint, mô hình hoặc tác vụ không tồn tại | Kiểm tra URL cuối cùng, ID mô hình, ID tác vụ và tài khoản sở hữu |
429 | Tần suất yêu cầu, số yêu cầu đồng thời, hạn mức hoặc dung lượng dịch vụ bị giới hạn | Dừng yêu cầu tần suất cao, giảm tải theo lỗi thực tế rồi thử lại sau |
500–599 | Nền tảng, gateway hoặc dịch vụ thượng nguồn tạm thời không thể hoàn thành yêu cầu | Lưu thông tin chẩn đoán và thử lại với backoff có giới hạn |
Các trạng thái này chỉ giúp định hướng nhanh. Mã lỗi chương trình của các giao thức và thượng nguồn có thể khác nhau; xác định nguyên nhân theo trạng thái HTTP, nội dung lỗi thực tế và API Reference tương ứng.
Quy trình khắc phục sự cố đề xuất
Ghi nhận hiện tượng thất bại
Lưu thời gian và múi giờ yêu cầu, Method, Path, ID mô hình, trạng thái HTTP và thông tin lỗi đã che dữ liệu nhạy cảm, giới hạn độ dài. Lưu kèm Request ID nếu phản hồi cung cấp.
Kiểm tra địa chỉ và xác thực
Dùng https://api.agtcloud.cn/v1 làm Base URL và đảm bảo URL cuối cùng không lặp /v1/v1. API tương thích OpenAI thường dùng Authorization: Bearer your-api-key; với giao thức khác, kiểm tra Header xác thực trong Reference tương ứng.
Kiểm tra mô hình và nội dung yêu cầu
Đảm bảo ID mô hình lấy từ danh sách mô hình khả dụng cho tài khoản; sau đó kiểm tra Content-Type, JSON, trường bắt buộc, loại tệp và kích thước đầu vào.
Xác định có nên thử lại
Cần sửa nguyên nhân của 400, 401, 403 và lỗi tài nguyên được xác nhận không tồn tại trước. Với lỗi mạng tạm thời hoặc 5xx, có thể thử lại có giới hạn và tăng dần thời gian chờ.
Chuẩn bị thông tin đã che dữ liệu nhạy cảm
Nếu vấn đề tiếp diễn, chuẩn bị bước tái hiện tối thiểu và thông tin chẩn đoán. Không sao chép Key đầy đủ, Prompt khách hàng, tệp hoặc phản hồi chưa che dữ liệu nhạy cảm để khắc phục sự cố.
Thử lại an toàn
- Với yêu cầu chỉ đọc thông thường gặp lỗi tạm thời, có thể thử lại với backoff có giới hạn.
- Chỉ gửi lại sau khi sửa nguyên nhân của vấn đề tham số, xác thực hoặc quyền.
- Trước khi gửi lại yêu cầu tạo tác vụ, gọi công cụ ngoài hoặc yêu cầu có tác dụng phụ khác, kiểm tra yêu cầu gốc đã có hiệu lực chưa.
- Với yêu cầu bất đồng bộ, ưu tiên truy vấn ID tác vụ gốc; không tạo tác vụ trùng chỉ vì ứng dụng hết thời gian chờ.
- Đặt số lần thử lại tối đa và tổng thời gian chờ; dừng yêu cầu tự động nếu tiếp tục thất bại và giữ thông tin chẩn đoán.
Thông tin cần chuẩn bị để khắc phục sự cố
| Thông tin | Ví dụ hoặc mô tả |
|---|---|
| Thời điểm xảy ra | Bao gồm ngày, giờ và múi giờ |
| Vị trí yêu cầu | Method và Path, không có API Key đầy đủ |
| Đích gọi | ID mô hình; có thể kèm ID tác vụ bất đồng bộ |
| Kết quả phản hồi | Trạng thái HTTP và lỗi đã che dữ liệu nhạy cảm |
| Đặc điểm yêu cầu | Có theo luồng, có công cụ hoặc là tác vụ bất đồng bộ hay không |
| Môi trường ứng dụng | Tên và phiên bản SDK, phiên bản runtime, bước tái hiện tối thiểu |
| Thông tin truy vết | Lưu Request ID nếu phản hồi cung cấp |
Để tra mã lỗi chương trình và cách xử lý, xem Tham khảo mã lỗi. Nếu chưa giải quyết được, xem tiếp Request ID và FAQ. Với vấn đề tích hợp lần đầu, kiểm tra lại Bắt đầu nhanh và API Key, Base URL và xác thực.