Lỗi AI API: 401, 403, 429 và 5xx

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.

Kiểm tra cụ thể theo từng lớp

Với 401

Kiểm tra Authorization: Bearer ..., dấu nháy hoặc khoảng trắng thừa, trạng thái khóa và secret cũ còn trong deployment. Lỗi này thường xảy ra trước định tuyến mô hình.

Với 403

Dùng cùng khóa để kiểm tra mô hình được phép, allowlist IP, quyền nhóm và chính sách tài khoản. Nếu chưa chọn kênh, đổi nhà cung cấp không sửa được bước từ chối trước đó.

Với 429

Xác định giới hạn thuộc khóa, tài khoản, nhóm hay tuyến. Tuân theo Retry-After, dùng backoff lũy thừa có độ trễ ngẫu nhiên và giới hạn số lần, tổng thời gian, mức song song.

Với 499

Bắt đầu từ ứng dụng khách: tín hiệu hủy, tab đã đóng, CDN, load balancer và timeout proxy. So sánh thời điểm hủy với đầu ra hữu ích đầu tiên; một 499 không chứng minh kênh gặp sự cố.

Phân biệt từng lỗi 5xx

500 có thể là lỗi adapter xác định, 502 là phản hồi upstream không hợp lệ hoặc thiếu, 503 là tạm thời không có tuyến, còn 504 là hết ngân sách thời gian. Giữ trạng thái gốc và chỉ thử lại thao tác an toàn với giới hạn nghiêm ngặt.

Bằng chứng an toàn để chẩn đoán

• ID yêu cầu và giờ UTC;
• endpoint và chế độ truyền luồng;
• mô hình được yêu cầu và nhóm đã chọn;
• 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;
• dấu hiệu ứng dụng khách đã hủy;
• mô tả đã làm sạch về tính năng như công cụ hoặc hình ảnh.

Không đưa toàn bộ khóa, prompt, phản hồi, body gốc, email hoặc IP rõ ra ngoài quy trình an toàn đã được phê duyệt rõ ràng.

Câu hỏi thường gặp

403 có chứng minh nhà cung cấp đang lỗi không?

Không. Tài khoản, khóa, mô hình, nhóm, IP hoặc chính sách tính năng có thể từ chối yêu cầu trước khi chọn nhà cung cấp.

499 có phải lỗi bình thường của mô hình upstream không?

Không. Trong bản ghi Modelflare, nó là hủy downstream được quan sát trước khi phản hồi hoàn tất.

Có nên thử lại mọi lỗi 5xx không?

Không. Chỉ lặp công việc an toàn, giới hạn số lần và tổng thời gian, đồng thời giữ lại lỗi đầu tiên.