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

Xác định điều thất bại

1. Ghi trạng thái HTTP, phương thức và đường dẫn yêu cầu thực tế. Trạng thái HTTP và mã lỗi ứng dụng mô tả lớp khác nhau; không thay thế cho nhau.
2. Đọc trường lỗi theo giao thức đã gọi. Phản hồi gốc, OpenAI, Claude và Gemini không cùng một cấu trúc.
3. Với yêu cầu truyền luồng, xem cả sự kiện lỗi và trạng thái hoàn thành. Với tác vụ bất đồng bộ, xem status tác vụ. HTTP 200 không bảo đảm tạo thành công.
4. Dùng bảng dưới để sửa yêu cầu hoặc quyết định thử lại. message là văn bản giải thích, không phải enum ổn định; không rẽ nhánh theo câu chữ.

Enum mã lỗi nền tảng

Đây là enum đầy đủ mã lỗi ứng dụng nền tảng. Tên là nhãn tham chiếu; giá trị code trong phản hồi là số. “HTTP thường gặp” là hướng dẫn khắc phục, không phải ánh xạ cố định cho mọi điểm cuối. Dùng trạng thái HTTP thực tế và thân phản hồi. code chuyển tiếp từ thượng nguồn có thể không thuộc enum này.

Chỉ HTTP 429 không phân biệt đáng tin cậy giới hạn tốc độ với giới hạn đồng thời. Chỉ phân biệt khi có mã lỗi số rõ ràng. Kiểm tra mã định danh mô hình trong danh sách mô hình; không tự viết lại giá trị model.

Đọc lỗi theo giao thức

Ví dụ dưới cho thấy cấu trúc phổ biến do nền tảng tạo, không phải một định dạng được bảo đảm cho mọi lỗi. Lỗi xác thực có thể do các lớp xử lý khác nhau trả về, và phản hồi chuyển tiếp thượng nguồn có thể giữ cấu trúc, mã chuỗi hoặc kiểu riêng. Nhận diện cấu trúc phản hồi thực tế trước khi phân tích. Nếu không nhận ra, giữ trường gốc và trạng thái HTTP thay vì ép chuyển đổi.

API nền tảng gốc

Thường đọc error.code và error.message. requestId có thể vắng mặt.

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

Một số lỗi có thể dùng code và message cấp cao nhất. Máy khách nên chấp nhận khác biệt này và không coi thiếu đối tượng error là bằng chứng thành công. Phản hồi xác thực tham số cũng có thể thiếu mã lỗi số. Coi mã thiếu là chưa biết thay vì bịa ra.

API tương thích OpenAI

Lỗi phổ biến do nền tảng tạo dùng code, message và type cấp cao nhất; không nhất thiết bọc trong error.

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type là nhóm giao thức; code là mã lỗi số nền tảng trong cấu trúc này. Chỉ api_error không quyết định thử lại có phù hợp không. Lỗi chuyển tiếp thượng nguồn và truyền luồng có thể chứa error lồng; xử lý phản hồi giao thức thực tế. Xem Chat Completions và Responses.

API tương thích Claude

Trong cấu trúc phổ biến, type cấp cao nhất là error, nhóm cụ thể là error.type và mô tả là error.message. Cấu trúc này không gồm code số nền tảng. Không bịa thêm.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

Nền tảng tạo cục bộ các kiểu lỗi Claude sau. Đây không phải enum đầy đủ kiểu lỗi thượng nguồn.

Xem Claude Messages.

Lỗi kiểu Gemini

Khi nhận phản hồi kiểu Gemini, đọc error.code, error.message và error.status. Ở đây, status là nhóm dạng chuỗi, không phải trạng thái HTTP hay trạng thái tác vụ bất đồng bộ.

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

Lỗi do nền tảng tạo theo cấu trúc này dùng giá trị code số nền tảng. Ánh xạ chuỗi status cục bộ ở dưới; đây không phải enum mọi trạng thái thượng nguồn.

503 được ưu tiên và dùng UNAVAILABLE, không phải INTERNAL. Phản hồi thượng nguồn có thể dùng ngữ nghĩa code và status khác. Không áp dụng bảng mã lỗi nền tảng cho mọi mã số Gemini.

Thử lại an toàn

Tuân theo tiêu đề Retry-After hợp lệ khi có. Không giả định mọi lỗi đều kèm tiêu đề này. Tự động thử lại yêu cầu tạo không lũy đẳng có thể thực thi lần nữa và phát sinh phí. Trang này không hứa hẹn hỗ trợ khóa lũy đẳng chung; tự thêm Idempotency-Key không bảo đảm loại trùng.

Nếu đã có jobId, truy vấn tác vụ đó trước khi tạo tác vụ khác. Nếu không có jobId và kết quả chưa rõ, giữ mã định danh yêu cầu cùng dấu thời gian để điều tra.

Luồng và tác vụ bất đồng bộ

Yêu cầu SSE

Sau khi SSE bắt đầu, trạng thái HTTP có thể vẫn là 200 trong khi lỗi sau đó được báo qua sự kiện lỗi hoặc tải dữ liệu trong luồng. Phân tích sự kiện và dữ liệu theo giao thức đã chọn, kiểm tra hoàn thành bình thường. Khi lỗi hay mất kết nối bất ngờ, không coi văn bản hoặc ảnh một phần là kết quả thành công hoàn chỉnh. Tên sự kiện và tải dữ liệu khác giữa các điểm cuối. Không chỉ kiểm tra một trường error cố định hay dùng “đã nhận bất kỳ văn bản nào” làm điều kiện thành công.

Tác vụ bất đồng bộ

Phản hồi tạo chứa data.jobId nghĩa là yêu cầu được chấp nhận, không phải tạo đã hoàn tất. Phản hồi HTTP thành công khi truy vấn tác vụ nghĩa là truy vấn thành công. Bạn vẫn phải xem data.status của tác vụ:

• PENDING, CONNECT, PROCESSING: tiếp tục thăm dò như mô tả trong tài liệu tác vụ.
• COMPLETED: đọc outputResult.
• FAILED, CANCELLED: dừng thăm dò và giữ ID tác vụ cùng thông tin phản hồi đã loại dữ liệu nhạy cảm để điều tra.

Chi tiết lỗi có thể ở data.outputResult.error. Trường này tùy chọn và không được bảo đảm cho mọi tác vụ thất bại. Chỉ dùng tác vụ khi phản hồi tạo trả rõ jobId. Không áp dụng thăm dò tác vụ cho điểm cuối trả kết quả trực tiếp qua JSON hoặc SSE.

Chẩn đoán cho người dùng và trợ lý AI

Cung cấp thông tin đã loại dữ liệu nhạy cảm sau cho hỗ trợ hoặc trợ lý AI. Dùng unknown cho trường vắng mặt; dùng unknown cho trạng thái HTTP nếu không nhận phản hồi HTTP. Giữ đường dẫn trường và kiểu giá trị gốc, ví dụ error.code: 10000 (number) hoặc error.code: "invalid_api_key" (string). Không tự chuyển code chuỗi thành mã số nền tảng hoặc bịa trường thiếu từ message, trạng thái HTTP hay tên mô hình.

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

Đọc requestId từ thân phản hồi hoặc tiêu đề phản hồi X-Request-ID khi có. Giữ jobId là chuỗi để tránh mất độ chính xác với số dài. Chỉ cung cấp tham số yêu cầu tối thiểu đã loại dữ liệu nhạy cảm. Bỏ khóa API, token, cookie, tiêu đề xác thực đầy đủ, thông tin cá nhân, câu lệnh riêng tư và nội dung tệp đầu vào. Bỏ tham số truy vấn URL và URL đầu vào hoặc đầu ra chứa chữ ký hay thông tin truy cập. Không dán nhật ký yêu cầu đầy đủ khi chưa rà soát.

Trợ lý AI nên phân biệt trường quan sát được với nguyên nhân có thể có, đồng thời xác định thông tin thiếu. Không được coi bằng chứng chưa đủ là chứng minh yêu cầu thành công, chưa thực thi hay không phát sinh phí.