Tham khảo mã lỗi

Tra cứu trạng thái HTTP phổ biến, mã lỗi tác vụ bất đồng bộ và mã lỗi chương trình của nền tảng.

Phản hồi lỗi thường có cả trạng thái HTTP và mã lỗi chương trình trong body. Ứng dụng cần đánh giá trạng thái HTTP trước, rồi đọc type, code và message thực sự được trả về; các trường có thể khác nhau theo giao thức hoặc thượng nguồn.

Để khắc phục theo hiện tượng, xem Lỗi và khắc phục sự cố trước. Trang này dùng để tra ý nghĩa lỗi, không thay thế mô tả phản hồi của Endpoint cụ thể.

Trạng thái HTTP

Trạng thái HTTP	Ý nghĩa phổ biến	Nguyên nhân phổ biến	Cách xử lý đề xuất
`400`	Yêu cầu không hợp lệ	JSON, trường bắt buộc, kiểu tham số, định dạng tệp hoặc nội dung đầu vào 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
`401`	Xác thực thất bại	API Key thiếu, không hợp lệ hoặc Header xác thực không đáp ứng giao thức	Kiểm tra Bearer hoặc Header riêng của giao thức và thay Key không hợp lệ
`403`	Thiếu quyền hoặc hạn mức	Tài khoản, Key, quyền mô hình, phạm vi IP hoặc hạn mức khả dụng không đáp ứng yêu cầu	Kiểm tra giới hạn tài khoản và Key, xác nhận mô hình mục tiêu khả dụng
`404`	Tài nguyên không tồn tại	Endpoint, ID mô hình, ID tác vụ hoặc Video ID không tồn tại	Kiểm tra URL cuối cùng, ID tài nguyên và tài khoản sở hữu
`429`	Yêu cầu bị giới hạn	Tần suất, số yêu cầu đồng thời, hạn mức hoặc dung lượng dịch vụ đạt giới hạn	Giảm tải và thử lại có giới hạn; lưu Request ID nếu tiếp tục thất bại
`500`	Xử lý yêu cầu thất bại	Lỗi trong chuyển đổi yêu cầu, tính Token, thông tin giá hoặc xử lý nền tảng	Lưu lỗi đã che thông tin nhạy cảm và Request ID, thử lại có giới hạn sau
`502`	Lỗi gateway thượng nguồn	Thượng nguồn trả phản hồi không hợp lệ hoặc gateway không thể chuyển tiếp	Thử lại có giới hạn; liên hệ hỗ trợ kỹ thuật nếu tiếp tục thất bại
`503`	Dịch vụ tạm thời không khả dụng	Nền tảng hoặc thượng nguồn quá tải, bảo trì hoặc tạm hết dung lượng xử lý	Thử lại với backoff; không liên tục gửi yêu cầu tần suất cao
`504`	Yêu cầu hết thời gian chờ	Thời gian xử lý thượng nguồn vượt thời gian chờ của gateway	Ghi Request ID; với tác vụ bất đồng bộ, ưu tiên truy vấn trạng thái tác vụ gốc

Không thể xác định nguyên nhân chỉ bằng trạng thái HTTP

404 có thể biểu thị đường dẫn, mô hình hoặc tác vụ không tồn tại; 429 có thể do tần suất, số yêu cầu đồng thời, hạn mức hoặc dung lượng dịch vụ. Ứng dụng cần đánh giá cùng nội dung lỗi thực tế và Request ID.

Cấu trúc bao lỗi phổ biến

API tương thích OpenAI thường dùng đối tượng error để chứa thông tin lỗi:

{
  "error": {
    "message": "Nguyên nhân cụ thể khiến yêu cầu thất bại",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Một số API tác vụ nền tảng trả trực tiếp code và message:

{
  "code": "task_not_exist",
  "message": "ID tác vụ được truy vấn không tồn tại"
}

Ứng dụng không nên giả định mọi API có cấu trúc bao lỗi giống hệt nhau. Xem API Reference tương ứng trước khi phân tích và xử lý tương thích khi thiếu trường tùy chọn.

Mã lỗi tác vụ bất đồng bộ

Tác vụ Midjourney

`code`	Trạng thái HTTP	Ý nghĩa với người dùng	Cách xử lý đề xuất
`1`	`200`	Gửi tác vụ thành công	Lưu ID tác vụ trả về và dùng API truy vấn để lấy tiến độ
`4`	`400`	Tham số yêu cầu sai	Kiểm tra Prompt, loại thao tác và trường bắt buộc
`21`	`200`	Tác vụ tương tự đã tồn tại	Tiếp tục dùng ID tác vụ trả về; không tạo trùng lặp
`22`	`200`	Tác vụ đang chờ trong hàng đợi	Giữ ID tác vụ và tiếp tục truy vấn sau
`23`	`429`	Hàng đợi tác vụ hiện đã đầy	Giảm tần suất gửi và thử lại sau
`24`	`400`	Prompt không vượt qua kiểm tra nội dung	Điều chỉnh Prompt rồi gửi lại
`3`	`403`	Tạm thời không thể gửi yêu cầu hiện tại	Lưu thông tin lỗi, thử lại sau hoặc liên hệ hỗ trợ kỹ thuật
`30`	`429`	Dung lượng xử lý của nhóm hiện đã đầy	Giảm số yêu cầu đồng thời và thử lại sau

Ví dụ gửi tác vụ thành công:

{
  "code": 1,
  "description": "Gửi thành công",
  "result": "TASK_ID"
}

Ví dụ tác vụ chờ trong hàng đợi:

{
  "code": 22,
  "description": "Đang chờ, có 2 tác vụ phía trước"
}

Tác vụ nền tảng

`code`	Trạng thái HTTP	Ý nghĩa với người dùng	Cách xử lý đề xuất
`task_not_exist`	`404`	Tác vụ không tồn tại hoặc không thuộc tài khoản hiện tại	Kiểm tra ID tác vụ, API Key và nút xử lý yêu cầu
`quota_not_enough`	`403`	Hạn mức hiện tại không đủ để tạo tác vụ	Kiểm tra hạn mức tài khoản và token truy cập; tránh thử lại nguyên yêu cầu
`invalid_api_platform`	`400`	Loại nền tảng trong yêu cầu không hợp lệ	Sửa tham số nền tảng hoặc giao thức
`fail_to_fetch_task`	Theo trạng thái thượng nguồn	Không lấy được trạng thái mới nhất từ nguồn tác vụ	Lưu ID tác vụ hiện tại, thử lại có giới hạn sau

Mã lỗi chương trình của nền tảng

`code`	Trạng thái HTTP phổ biến	Ý nghĩa với người dùng	Cách xử lý đề xuất
`invalid_request`	`400`	Định dạng yêu cầu hoặc tham số không hợp lệ	Kiểm tra JSON, trường bắt buộc và kiểu trường
`read_request_body_failed`	`400`	Không đọc được body yêu cầu	Kiểm tra kích thước body yêu cầu, kết nối và Content-Type
`sensitive_words_detected`	`400`	Đầu vào không vượt qua kiểm tra nội dung	Điều chỉnh đầu vào rồi gửi lại
`prompt_blocked`	`400`	Prompt bị chính sách nội dung chặn	Điều chỉnh Prompt theo thông tin lỗi
`access_denied`	`403`	Yêu cầu hiện tại bị từ chối	Kiểm tra API Key, trạng thái tài khoản và phạm vi IP được phép
`insufficient_user_quota`	`403`	Hạn mức tài khoản khả dụng không đủ	Kiểm tra số dư hoặc hạn mức trước khi gửi lại
`pre_consume_token_quota_failed`	`403`	Hạn mức token truy cập khả dụng không đủ	Kiểm tra hạn mức và giới hạn sử dụng của Key hiện tại
`model_not_found`	`404`	Tài khoản hiện tại không tìm thấy mô hình mục tiêu	Sao chép lại ID mô hình khả dụng từ danh mục mô hình
`convert_request_failed`	`500`	Không chuyển đổi được yêu cầu sang giao thức đích	Kiểm tra Endpoint, giao thức và tính tương thích của mô hình mục tiêu
`count_token_failed`	`500`	Không tính được lượng Token của yêu cầu	Lưu đặc điểm yêu cầu đã che thông tin nhạy cảm và Request ID
`do_request_failed`	`500`	Nền tảng không hoàn thành được yêu cầu thượng nguồn	Kiểm tra trạng thái mạng và thử lại có giới hạn
`bad_response_status_code`	Theo trạng thái thượng nguồn	Thượng nguồn trả lỗi không chuẩn hoặc không thể phân tích trực tiếp	Lưu trạng thái HTTP gốc, thông báo đã che dữ liệu nhạy cảm và Request ID
`api_not_implemented`	`501`	Endpoint hiện chưa khả dụng	Kiểm tra API Reference và chuyển sang Endpoint đã công khai

Nguyên tắc xử lý phía ứng dụng

Ghi đồng thời trạng thái HTTP, mã lỗi chương trình, thông báo đã che dữ liệu nhạy cảm và Request ID.
Với 400, 401, 403, sửa nguyên nhân trước; không tự động thử lại nguyên yêu cầu.
Với 404, kiểm tra đường dẫn và ID tài nguyên; tài nguyên bất đồng bộ còn cần kiểm tra tài khoản sở hữu.
Với 429, 502, 503, 504, có thể thử lại với backoff có giới hạn.
Trước khi gửi lại yêu cầu tạo tác vụ 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.
Không dựa vào toàn bộ nội dung thông báo lỗi để phân nhánh chương trình; ưu tiên trạng thái HTTP và code ổn định.

Để lưu thông tin truy vết, xem Request ID; để có hướng dẫn khắc phục và thử lại đầy đủ hơn, xem Lỗi và khắc phục sự cố.