Lỗi và thử lại API AI: đừng tạo thêm vấn đề
Phân biệt yêu cầu cần sửa với lỗi tạm thời và tránh tạo trùng tác vụ bất đồng bộ.

Đọc lỗi trước khi gửi lại
Yêu cầu sai định dạng, khóa không hợp lệ hoặc tham số không được hỗ trợ thường cần sửa cấu hình thay vì gửi lại y nguyên. Giới hạn tốc độ và lỗi tạm thời có thể cần thử lại theo tài liệu. Lưu trạng thái và mã yêu cầu nhưng không ghi khóa hay prompt nhạy cảm vào nhật ký.
Lỗi xác thực hoặc quyền cần kiểm tra khóa và quyền truy cập. Sai định dạng, tên mô hình hay tham số cần sửa yêu cầu. Giới hạn tốc độ hoặc lỗi dịch vụ tạm thời có thể cho phép thử lại theo tài liệu. Gọi tất cả là “lỗi mạng” làm mất dấu vết hữu ích và dễ gây gửi lại vô nghĩa.
Cho lỗi tạm thời thời gian phục hồi
Với lỗi được phép thử lại, giới hạn số lần, tăng dần thời gian chờ và thêm độ ngẫu nhiên. Tôn trọng thời gian chờ do máy chủ cung cấp khi có, đồng thời đặt hạn chót tổng thể. Không thử lại mọi lỗi và tránh để nhiều máy khách cùng gửi lại một lúc.
Với lỗi được tài liệu cho phép thử lại, giới hạn số lần và tổng thời gian, tăng dần độ trễ và thêm biến thiên ngẫu nhiên để tránh nhiều máy khách gửi lại cùng lúc. Tôn trọng thời gian chờ máy chủ chỉ định. Cho phép người dùng hủy; khi hết giới hạn, dừng thay vì tiêu thụ tài nguyên vô hạn trong nền.
Khi gặp lỗi tạm thời, hãy chờ và thử lại theo một chiến lược có kiểm soát.Cẩn thận với tác vụ có tác động
Hết thời gian chờ có thể xảy ra sau khi máy chủ đã nhận yêu cầu. Tạo thêm tác vụ ảnh hoặc video có thể lặp công việc và chi phí. Lưu mã tác vụ đã trả về và kiểm tra trạng thái trước khi gửi lại; chỉ dựa vào cơ chế idempotency khi endpoint ghi rõ hỗ trợ.
Hết thời gian sau khi gửi có thể nghĩa là phản hồi bị mất dù tác vụ từ xa đã tạo. Lưu và kiểm tra ID nếu nhận được; nếu không có ID, đừng mặc định tác vụ không tồn tại. Xem endpoint có tài liệu về tra cứu, callback hay idempotency không và làm theo quy trình khôi phục. Giải thích khả năng phát sinh phí trước khi tạo mới.
Nói rõ bước tiếp theo với người dùng
Cho biết họ nên thử lại, sửa đầu vào hay quay lại sau. Khi phù hợp, giữ phần văn bản streaming đã nhận và đánh dấu là chưa hoàn chỉnh. Kiểm thử riêng yêu cầu sai, giới hạn tốc độ, mất mạng và tác vụ chậm; không nên dùng cùng một thông báo mơ hồ cho tất cả.
Thời gian, mã yêu cầu, endpoint, trạng thái, thời lượng và loại lỗi cần thiết thường đủ để bắt đầu điều tra. Không ghi khóa đầy đủ, header xác thực hay prompt người dùng không cần thiết; kiểm tra dữ liệu cá nhân trước khi chia sẻ. Người dùng cần bước tiếp theo rõ ràng, còn người vận hành cần ngữ cảnh có thể truy vết nhưng giới hạn.
Mô phỏng riêng tham số sai, lỗi xác thực, giới hạn tốc độ, mất kết nối và tác vụ bất đồng bộ chậm. Xác nhận chỉ lỗi phù hợp mới được thử lại, thời gian chờ có giới hạn và giao diện giữ kết quả một phần khi cần. Thử bấm lại nhiều lần để phát hiện tác vụ trùng. Không cần dữ liệu khách thật hoặc tác vụ tính phí trên production.
Xác định loại lỗi
Lưu mã trạng thái, mã yêu cầu, thời điểm và loại lỗi đã loại bỏ thông tin nhạy cảm. Lỗi xác thực cần kiểm tra khóa hoặc quyền; tham số sai cần sửa yêu cầu. Giới hạn tốc độ và lỗi tạm thời có thể cho phép thử lại theo tài liệu API.
Quá thời gian sau khi gửi không chứng minh dịch vụ từ xa chưa làm gì: tác vụ có thể đang chạy hoặc đã xong. Hãy hướng dẫn người dùng bước tiếp theo mà không để lộ khóa hay thông tin nội bộ.
Đặt giới hạn cho việc thử lại
Với lỗi có thể thử lại an toàn, đặt số lần tối đa và tổng thời gian chờ. Khoảng chờ tăng dần kèm độ lệch ngẫu nhiên giúp tránh nhiều máy khách thử lại cùng lúc. Tuân theo hướng dẫn chờ của API nếu có.
Tránh để trình duyệt, máy chủ và thư viện cùng nhân số lần thử. Với thao tác tạo hoặc ghi, dùng cơ chế chống trùng thực sự được hỗ trợ hoặc kiểm tra tác vụ đã biết. Nếu kết quả chưa rõ, hãy thông báo điều đó.
Kiểm tra chiến lược qua hai ví dụ
Khi nhận thông báo giới hạn tốc độ rõ ràng, giữ dữ liệu người dùng, tuân theo thời gian chờ và cho phép hủy. Nếu hết số lần thử, dừng trạng thái tải và giải thích kết quả.
Nếu kết nối mất trước khi nhận mã tác vụ video, dùng cơ chế khôi phục được hỗ trợ và không âm thầm tạo nhiều tác vụ. Hãy kiểm tra thêm khóa sai, tham số lỗi và hủy; phân loại cảnh báo theo thời gian và mức ảnh hưởng.
Hai lỗi cần hai cách xử lý
Nếu bị giới hạn tốc độ và dịch vụ trả thời gian chờ, hãy đợi theo chỉ dẫn trong giới hạn thử lại. Nếu yêu cầu tạo video hết thời gian sau khi gửi, tác vụ có thể đã tồn tại: tìm ID đã lưu và kiểm tra trạng thái trước. Nếu không nhận được ID, hãy báo tình trạng chưa chắc chắn và làm theo tài liệu thay vì mặc định gửi lại là miễn phí.
Khi liên hệ hỗ trợ, cung cấp thời gian, tên mô hình, mã yêu cầu và mô tả lỗi đã ẩn dữ liệu nhạy cảm. Đừng yêu cầu người dùng đăng khóa hoặc toàn bộ nội dung riêng tư ở kênh công khai. Kiểm tra xem tác vụ đã tồn tại chưa trước khi đề xuất bước xử lý hoặc thử lại an toàn.