Mã lỗi và khắc phục

Khi khắc phục trước tiên ghi lại: mã trạng thái HTTP, định danh yêu cầu do nền tảng trả về, ID mô hình, ID tác vụ, ID tư liệu và mã lỗi gốc.

Đừng ghi lại khóa API, Token phiên người thật hoặc địa chỉ tải tư liệu đầy đủ; trước khi gửi cho hỗ trợ nền tảng hãy che thông tin nhạy cảm trước.

Ý nghĩa trạng thái HTTP

404 có ba nguyên nhân, đừng mặc định cho rằng "viết sai ID"

Đây là điểm dễ chẩn đoán nhầm nhất khi khắc phục:

Khi nhận 404, trước tiên xác nhận đường dẫn và phương thức có khớp nhau không, rồi mới nghi ngờ ID.

Không tìm thấy tác vụ video trả về 400, không phải 404

Điểm này không nhất quán với các API khác, cần đặc biệt lưu ý:

Truy vấn tác vụ video trả về bằng cấu trúc 400 + cấp cao nhất {code, message, data}, không phải 404, cũng không phải cấu trúc đối tượng error nói dưới đây.

Phản hồi lỗi có ba cấu trúc

1. API tạo sinh mô hình / hình ảnh / video — đối tượng error

Khi thất bại trả về HTTP không phải 2xx, kèm một đối tượng error:

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

code có thể là chuỗi rỗng. Thực tế: khi xác thực thất bại và khi JSON phần thân yêu cầu không phân tích được, code đều là "". Đừng dùng việc code có rỗng hay không để phán đoán "có phải lỗi không", hãy lấy mã trạng thái HTTP làm chuẩn, và ưu tiên đọc message.

type không phải trường phân loại ổn định. Khi cần phân loại hãy đọc code, đừng phụ thuộc vào giá trị của type.

2. API thư viện tư liệu — code cấp cao nhất

Trả về HTTP không phải 2xx, code trùng với trạng thái HTTP:

{ "code": 404, "data": null, "msg": "素材不存在或无权访问" }

3. Truy vấn tác vụ video — chuỗi code cấp cao nhất

{ "code": "task_not_exist", "message": "task_not_exist", "data": null }

Lưu ý code ở đây là chuỗi task_not_exist, không phải số.

request id: định danh then chốt để khắc phục vấn đề

Nền tảng ghi thẳng request id vào error.message, không cần tìm trong header:

"message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)"

Lấy ra bằng một dòng lệnh:

curl -s "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer sk-invalid" \
  | grep -oE 'request id: [A-Za-z0-9]+'

Khi gửi ticket kèm request id này, có thể rút ngắn đáng kể thời gian định vị.

Xác thực thất bại

Khi API keys thiếu, sai hoặc đã hết hiệu lực, tất cả API đều trả về HTTP 401 và:

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: ...)",
    "type": "new_api_error"
  }
}

Lưu ý code là chuỗi rỗng — đây chính là lý do phần trên nhắc "đừng phụ thuộc code".

Lỗi mô hình và tạo sinh

Lỗi thư viện tư liệu

Tư liệu chưa duyệt xong không phải lỗi: truy vấn trả về 200, status là Processing, chỉ cần tiếp tục poll cùng một ID tư liệu.

Mô hình suy luận xuất ra rỗng cũng không phải lỗi HTTP: nếu trả về 200, finish_reason là length, và usage.completion_tokens_details.reasoning_tokens đã chiếm đầy giới hạn đầu ra, nên tăng hạn mức đầu ra hoặc đổi sang mô hình không suy luận.

Lỗi ủy quyền chân dung

Giới hạn tần suất và thử lại

• 429 nghĩa là yêu cầu quá thường xuyên, lùi lại thử lại theo thông báo, không thử lại đồng thời;
• Trạng thái tư liệu khuyến nghị truy vấn mỗi 5～10 giây, tác vụ video mỗi 5～15 giây;
• Chỉ thử lại với 429 và 5xx tạm thời; 400 / 401 / 403 / 404 sửa trực tiếp yêu cầu;
• Trước khi thử lại hãy truy vấn theo ID tác vụ / ID tư liệu, tránh tạo trùng và tính phí trùng.

Tự kiểm tra nhanh

1. Authorization có phải Bearer <API Key>, Key còn ở trạng thái bật hay không;
2. Tên miền yêu cầu có phải địa chỉ hiện được chỉ định trong bảng điều khiển (mặc định https://locopalai.com, mô hình hải ngoại có thể là https://us-api.locopalai.com);
3. model có đến từ data[].id của /v1/models hay không;
4. status của tư liệu đã là Active chưa;
5. Địa chỉ ảnh / video tham chiếu có phải địa chỉ http(s) truy cập trực tiếp từ công cộng, và không phụ thuộc Cookie hay Referer;
6. Cùng một tác vụ / tư liệu đã từng bị gửi trùng chưa.

Khi gửi hỗ trợ vui lòng kèm theo

• Thời gian yêu cầu và đường dẫn API;
• Mã trạng thái HTTP và phần thân phản hồi đầy đủ (che khóa API);
• Định danh yêu cầu, ID tác vụ hoặc ID tư liệu do nền tảng trả về;
• ID mô hình và tham số liên quan;
• Ví dụ yêu cầu tối thiểu có thể tái hiện.