Lỗi API

Trang này cung cấp thông tin tham khảo về tất cả mã lỗi của Interactions API, mô tả định dạng phản hồi lỗi và giải thích cách API này gửi lỗi cho các loại yêu cầu khác nhau.

Mã lỗi API chuẩn

Các mã lỗi chung ở cấp yêu cầu này tương ứng với mã trạng thái HTTP chuẩn. Sử dụng trường code trong logic ứng dụng để xử lý lỗi theo phương thức lập trình.

Mã chặn tạo

Các mã lỗi này cho biết rằng các quy định hạn chế về chính sách, an toàn hoặc giới hạn nội dung đã chặn kết quả của mô hình. Khi bạn nhận được một trong các mã này, hãy sửa đổi dữ liệu đầu vào rồi thử lại.

Mã lỗi khi tạo

Các mã lỗi này cho biết vấn đề về cấu trúc với kết quả do mô hình tạo ra (chẳng hạn như lệnh gọi hàm không đúng định dạng hoặc lệnh gọi công cụ chưa khai báo).

Định dạng phản hồi lỗi

Tất cả lỗi từ Interactions API đều trả về một đối tượng error chứa code và message. Ví dụ: việc truyền một loại công cụ không được hỗ trợ sẽ trả về:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}

Cách thông báo lỗi

API này gửi lỗi theo cách khác nhau tuỳ thuộc vào việc bạn gửi yêu cầu HTTP tiêu chuẩn hay yêu cầu truyền trực tuyến (SSE).

Yêu cầu HTTP chuẩn

Đối với các yêu cầu tiêu chuẩn (không truyền trực tuyến), API sẽ đặt mã trạng thái phản hồi HTTP (chẳng hạn như 400 Bad Request, 401 Unauthorized hoặc 429 Too Many Requests) và trả về một đối tượng error trong phần nội dung phản hồi JSON:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

Yêu cầu truyền trực tuyến (SSE)

Đối với các yêu cầu truyền trực tuyến (stream: true), API sẽ gửi các sự kiện lỗi qua luồng Sự kiện do máy chủ gửi (SSE) với event_type được đặt thành "error". Trường error chứa cùng cấu trúc code và message:

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

Để biết giản đồ sự kiện SSE đầy đủ, hãy xem Tài liệu tham khảo về Interactions API.

Bước tiếp theo

• Khắc phục sự cố về API: Giải quyết các vấn đề và trường hợp lỗi thường gặp.
• Giới hạn số lượng yêu cầu: Tìm hiểu về giới hạn số lượng yêu cầu và cách xử lý hạn mức.