Hướng dẫn lỗi API AI: 401, 403, 429 và 5xx
Chẩn đoán lỗi xác thực, chính sách truy cập, giới hạn tốc độ, ứng dụng khách hủy yêu cầu và lỗi từ nhà cung cấp dịch vụ, rồi quyết định khi nào thử lại là an toàn.

Lỗi API AI dễ chẩn đoán nhất khi mã trạng thái được xem là điểm khởi đầu của quá trình điều tra, chứ không phải toàn bộ nguyên nhân. Hãy lưu lại ID yêu cầu, thời điểm, endpoint, mô hình, tên khóa API, nhóm đã chọn, nội dung phản hồi và thời gian trước khi thử lại.
Mục tiêu là xác định lớp nào đã từ chối hoặc kết thúc yêu cầu: ứng dụng khách, xác thực, chính sách truy cập, kiểm tra giao thức, định tuyến, backend mô hình hay kết nối phía ứng dụng khách.
Các mã trạng thái phổ biến thường cho biết điều gì
| Trạng thái | Cách hiểu ban đầu | Việc cần làm trước |
|---|---|---|
| 400 | Cấu trúc yêu cầu, trường hoặc hợp đồng giao thức không hợp lệ | So sánh payload với endpoint đã chọn; không thử lại khi chưa thay đổi gì |
| 401 | Thông tin xác thực bị thiếu, sai định dạng, đã tắt, đã hết hạn hoặc không hợp lệ | Kiểm tra header Authorization và khóa hiện tại |
| 403 | Đã xác thực nhưng bị chặn bởi tài khoản, mô hình, nhóm, IP hoặc chính sách | Kiểm tra giới hạn của khóa và quyền truy cập mô hình/nhóm trước khi thử kênh |
| 404 | Sai đường dẫn endpoint hoặc mã định danh mô hình không khả dụng | Xác minh Base URL, đường dẫn và danh sách mô hình đã xác thực |
| 429 | Giới hạn tốc độ yêu cầu, hạn mức hoặc giới hạn của tuyến đủ điều kiện | Kiểm tra hạn mức và giới hạn của nhóm; dùng backoff có giới hạn hoặc dự phòng đã cấu hình |
| 499 | Ứng dụng khách phía dưới đã ngắt kết nối hoặc hủy trước khi hoàn tất | Kiểm tra hạn chót, lệnh hủy, proxy của ứng dụng khách và thời gian đến đầu ra đầu tiên |
| 500 | Lỗi xử lý nội bộ hoặc lỗi bộ chuyển đổi | Lưu ID yêu cầu; chỉ thử lại nếu thao tác an toàn |
| 502/503 | Phản hồi không hợp lệ từ nhà cung cấp dịch vụ, tuyến không khả dụng hoặc thiếu năng lực tạm thời | Kiểm tra bằng chứng về tuyến và dùng dự phòng hoặc thử lại có giới hạn |
| 504 | Ngân sách thời gian của gateway hoặc nhà cung cấp dịch vụ đã hết | So sánh thời gian đến đầu ra đầu tiên và tổng thời gian với hạn chót của ứng dụng khách |
Những cách hiểu này là điểm khởi đầu để chẩn đoán. Nội dung lỗi và bản ghi yêu cầu mới xác định lý do thực tế của từng lệnh gọi cụ thể.
Chẩn đoán 401 trước khi đổi mô hình
Lỗi 401 thường xảy ra trước khi có bước định tuyến mô hình hữu ích nào. Hãy kiểm tra:
- header có dùng Authorization: Bearer ...;
- ứng dụng không chèn dấu ngoặc kép, khoảng trắng hoặc giá trị giữ chỗ;
- khóa đang bật và chưa hết hạn;
- yêu cầu được gửi đến đúng máy chủ Modelflare dự định;
- trình quản lý bí mật hoặc bản triển khai không còn giữ một khóa cũ đã được xoay vòng.
Không dán toàn bộ khóa vào nhật ký hoặc tin nhắn gửi bộ phận hỗ trợ. Nếu khóa có thể đã bị lộ, hãy tái hiện lỗi bằng một khóa thử nghiệm riêng, sau đó thu hồi thông tin xác thực bị lộ.
Chẩn đoán 403 trước hết như lỗi chính sách truy cập
Lỗi 403 không tự động có nghĩa là nhà cung cấp dịch vụ đã từ chối yêu cầu. Xác thực có thể thành công trong khi quyền truy cập bị từ chối trước khi chọn kênh, vì:
- khóa giới hạn mô hình được yêu cầu;
- danh sách IP được phép của khóa không bao gồm IP ứng dụng khách mà hệ thống ghi nhận;
- tài khoản không thể dùng nhóm mô hình đã chọn;
- người dùng hoặc khóa bị tắt theo chính sách;
- tính năng được yêu cầu không được phép trên tuyến đó.
Hãy gọi /v1/models bằng cùng khóa, kiểm tra giới hạn nhóm và mô hình của khóa, rồi so sánh mã lỗi chính xác. Nếu chưa có kênh nào được chọn, việc đổi kênh của nhà cung cấp dịch vụ không thể sửa quyết định chính sách đã xảy ra trước đó.
Chẩn đoán 429 mà không gây bão thử lại
Lỗi 429 là tín hiệu về năng lực hoặc chính sách, không phải chỉ dẫn để thử lại ngay trong một vòng lặp dày đặc. Hãy xác định giới hạn thuộc về hạn mức của khóa, tài khoản, nhóm mô hình hay tuyến đã chọn.
Với giới hạn tốc độ có thể thử lại:
- tuân theo Retry-After nếu có;
- dùng exponential backoff kèm jitter;
- giới hạn số lần thử và tổng thời gian;
- giữ số yêu cầu đồng thời của ứng dụng trong một giới hạn đã biết;
- chỉ dùng nhóm dự phòng theo thứ tự khi chúng giữ nguyên mô hình và giao thức được yêu cầu.
Tạo thêm khóa API không nhất thiết giúp vượt qua giới hạn yêu cầu ở cấp tài khoản hoặc nhóm.
Chẩn đoán 499 từ phía gọi trở ra
Modelflare có thể ghi nhận 499 khi kết nối của ứng dụng khách phía dưới kết thúc trước khi phản hồi hoàn tất. Hãy bắt đầu từ phía gọi:
- Có tín hiệu hủy nào được kích hoạt không?
- Ứng dụng khách, bộ cân bằng tải, CDN hoặc reverse proxy có chạm thời gian chờ khi không hoạt động hoặc thời gian chờ tổng không?
- Người dùng có đóng trang hoặc dừng agent không?
- Stream có tạo event công cụ mà không có văn bản hiển thị không?
- Đã mất bao lâu trước khi có đầu ra hữu ích đầu tiên?
Chỉ một bản ghi 499 không đủ để kết luận kênh gặp sự cố. Hãy so sánh các yêu cầu khác trong cùng khoảng thời gian với cùng mô hình/nhóm trước khi thay đổi chính sách định tuyến.
Phân tách lỗi 5xx theo từng lớp
Với 5xx, hãy giữ nguyên trạng thái gốc và chi tiết lỗi thay vì chuyển mọi lỗi thành một lỗi 500 chung chung ở ứng dụng khách.
- Lỗi 500 do kiểm tra tính hợp lệ hoặc do bộ chuyển đổi có thể mang tính xác định và sẽ lỗi lại nếu không thay đổi gì.
- Lỗi 502 có thể cho thấy phản hồi từ nhà cung cấp dịch vụ không hợp lệ hoặc không đầy đủ.
- Lỗi 503 có thể cho thấy không có tuyến đủ điều kiện hoặc dịch vụ tạm thời không khả dụng.
- Lỗi 504 cho thấy một ngân sách thời gian đã hết, nhưng vẫn cần xác định lớp chịu trách nhiệm.
Hãy dùng thời gian của yêu cầu, nhóm đã chọn, bằng chứng về kênh mà bộ phận hỗ trợ có thể xem và các yêu cầu lân cận để phân biệt một phản hồi lỗi đơn lẻ với sự cố tuyến kéo dài.
Quyết định có nên thử lại
| Loại lỗi | Quyết định thử lại mặc định |
|---|---|
| Payload không hợp lệ hoặc giao thức không được hỗ trợ | Sửa yêu cầu; không thử lại khi chưa thay đổi gì |
| Khóa không hợp lệ hoặc bị từ chối truy cập | Sửa thông tin xác thực hoặc chính sách; không thử lại khi chưa thay đổi gì |
| Hết hạn mức | Chủ động tăng hoặc phân bổ lại hạn mức; không lặp lại liên tục |
| Giới hạn tốc độ | Thử lại với backoff có giới hạn khi được phép |
| Lỗi 502/503/504 tạm thời | Thử lại tác vụ idempotent với ngân sách số lần thử nghiêm ngặt |
| Ứng dụng khách hủy | Chỉ thử lại nếu người dùng vẫn cần kết quả và việc trùng lặp là an toàn |
| Tác dụng phụ từ công cụ hoặc thao tác ghi | Yêu cầu cơ chế idempotent ở cấp ứng dụng trước khi lặp lại |
Mỗi lần thử lại tạo ra công việc mới và có thể phát sinh chi phí mới. Hãy ghi lại mọi lần thử và tránh để một lần thành công sau đó che giấu lỗi ban đầu.
Bằng chứng cần thu thập an toàn
Để gửi bộ phận hỗ trợ hoặc rà soát sự cố, hãy thu thập:
- ID yêu cầu và thời điểm theo UTC;
- endpoint và chế độ streaming;
- mô hình được yêu cầu và nhóm đã chọn;
- mã trạng thái HTTP và mã lỗi có cấu trúc;
- tổng thời gian và thời gian đến đầu ra hữu ích đầu tiên;
- phía gọi có hủy yêu cầu hay không;
- mô tả đã lược bỏ thông tin nhạy cảm về tính năng của yêu cầu, chẳng hạn công cụ hoặc đầu vào hình ảnh.
Không đưa vào toàn bộ khóa API, prompt, nội dung phản hồi, nội dung yêu cầu thô, email hoặc địa chỉ IP dạng văn bản thuần, trừ khi một quy trình bảo mật đã được phê duyệt yêu cầu cụ thể.
Sau khi xác định được lớp gây lỗi, hãy dùng Định tuyến API AI ổn định để thiết kế dự phòng và Hướng dẫn streaming cho các lỗi về event và thời gian chờ.
Câu hỏi thường gặp
Lỗi 403 có chứng minh nhà cung cấp đang gặp sự cố không?
Không. Lỗi 403 có thể do chính sách về tài khoản, khóa, mô hình, nhóm, IP hoặc tính năng tạo ra trước khi tuyến của nhà cung cấp dịch vụ được chọn. Hãy kiểm tra bản ghi yêu cầu và mã lỗi trước.
499 có phải là lỗi mô hình tiêu chuẩn của nhà cung cấp dịch vụ không?
Không. Trong bản ghi yêu cầu của Modelflare, mã này biểu thị việc hủy từ phía ứng dụng khách được ghi nhận trước khi hoàn tất. Hãy kiểm tra hạn chót của phía gọi và của proxy trước khi coi đó là lỗi mô hình.
Có nên thử lại mọi phản hồi 5xx không?
Không. Chỉ thử lại những thao tác an toàn khi lặp lại, dùng ngân sách số lần thử và thời gian có giới hạn, đồng thời giữ lại lỗi đầu tiên. Các vấn đề mang tính xác định ở bộ chuyển đổi hoặc ở yêu cầu sẽ không được cải thiện khi lặp lại.