Lỗi AI API: 401, 403, 429 và 5xx
Chẩn đoán xác thực, policy, giới hạn, cancellation và upstream theo từng lớp rồi quyết định thử lại an toàn.
HTTP status là điểm bắt đầu chẩn đoán AI API, không phải toàn bộ nguyên nhân. Trước khi thử lại, giữ request ID, giờ UTC, endpoint, mô hình, tên khóa, nhóm, lỗi có cấu trúc và timing. Sau đó xác định yêu cầu dừng ở ứng dụng, xác thực, policy, giao thức, định tuyến, backend hay kết nối downstream.
Cách hiểu ban đầu
| Status | Ý nghĩa đầu tiên | Hành động đầu tiên |
|---|---|---|
| 400 | Payload hoặc hợp đồng không hợp lệ | Sửa, không gửi lại nguyên trạng |
| 401 | Khóa thiếu, sai hoặc hết hạn | Kiểm tra Authorization và khóa hiện tại |
| 403 | Policy tài khoản, mô hình, nhóm hoặc IP | Kiểm tra giới hạn khóa trước channel |
| 404 | Sai path hoặc model ID | Kiểm tra Base URL và /v1/models |
| 429 | Giới hạn quota, tốc độ hoặc tuyến | Tìm lớp giới hạn và backoff có giới hạn |
| 499 | Ứng dụng hủy trước khi xong | Kiểm tra deadline, Abort, proxy, output đầu |
| 502/503/504 | Upstream, khả dụng hoặc ngân sách thời gian | Giữ bằng chứng và thử lại có giới hạn |
Chẩn đoán theo từng lớp
401 thường xuất hiện trước định tuyến. Kiểm tra Authorization: Bearer ..., trạng thái khóa, host và Secret cũ trong deployment. Không đưa toàn bộ khóa vào log hoặc ticket.
403 không chứng minh nhà cung cấp từ chối. Giới hạn mô hình, IP allowlist, quyền nhóm hoặc policy tài khoản có thể chạy trước khi chọn channel. Gọi /v1/models bằng cùng khóa và xem mã lỗi chính xác.
Với 429, xác định khóa, tài khoản, nhóm hay tuyến bị giới hạn. Tuân theo Retry-After, dùng exponential backoff có jitter và giới hạn số lần, tổng thời gian, concurrency. Thêm khóa chưa chắc vượt được giới hạn tài khoản.
499 ghi nhận kết nối downstream đã kết thúc. Bắt đầu từ Abort, trình duyệt, CDN, load balancer và proxy; so sánh output hiệu quả đầu tiên. Một bản ghi không chứng minh channel gặp sự cố.
Quyết định thử lại
- Request, khóa hoặc quyền sai: sửa nguyên nhân, không lặp nguyên trạng.
- Rate limit: chỉ backoff có giới hạn khi được phép.
- 502, 503, 504 tạm thời: chỉ workload idempotent với ngân sách nghiêm ngặt.
- Cancellation: xác nhận vẫn cần kết quả và không lặp side effect.
- Công cụ hoặc ghi dữ liệu: cần idempotency ở ứng dụng trước.
Mỗi lần thử có thể tạo công việc và chi phí. Có thể chia sẻ ID, giờ, endpoint, streaming, mô hình, nhóm, status, code và timing; không chia sẻ toàn bộ khóa, prompt, response, body, email hoặc IP rõ. Sau đó dùng hướng dẫn định tuyến và streaming.