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 gửi lỗi cho các loại yêu cầu khác nhau.

Mã lỗi API tiêu 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 tiêu 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ã Trạng thái HTTP Mô tả Hành động được đề xuất
invalid_request 400 Yêu cầu không hợp lệ Tải trọng yêu cầu sai định dạng hoặc chứa các tham số không hợp lệ. Kiểm tra cú pháp và các tham số của yêu cầu dựa trên tài liệu tham khảo API.
failed_precondition 400 Yêu cầu không hợp lệ Chúng tôi không thể xử lý yêu cầu vì bạn chưa đáp ứng một điều kiện tiên quyết (ví dụ: đã tắt tính năng thanh toán). Xác minh trạng thái thanh toán của dự án hoặc các điều kiện tiên quyết về tài khoản.
out_of_range 416 Không đáp ứng phạm vi yêu cầu Tham số yêu cầu nằm ngoài phạm vi hợp lệ. Kiểm tra các giá trị và giới hạn của tham số.
parameter_unknown 400 Yêu cầu không hợp lệ Yêu cầu chứa một tham số không xác định. Xoá tham số không nhận dạng được rồi thử lại.
authentication 401 Không được phép Khoá API bị thiếu, không hợp lệ hoặc đã hết hạn. Xác minh khoá API.
permission_denied 403 Bị cấm Khoá API của bạn không có quyền truy cập vào tài nguyên này. Kiểm tra quyền khoá API và quyền truy cập vào dự án.
not_found 404 Không tìm thấy Không tìm thấy tài nguyên được yêu cầu. Xác minh đường dẫn tài nguyên và các tham số.
model_not_found 404 Không tìm thấy Không tìm thấy mô hình được chỉ định. Xác minh tên mô hình hoặc chuyển sang một mô hình khác.
already_exists 409 Xung đột Thực thể mà bạn tìm cách tạo đã tồn tại. Kiểm tra xem tài nguyên đã tồn tại hay chưa trước khi tạo lại.
aborted 409 Xung đột Thao tác bị huỷ do xung đột hoặc không thực hiện được quy trình kiểm tra tính đồng thời. Thử lại yêu cầu ở cấp ứng dụng cao hơn.
rate_limit_exceeded 429 Quá nhiều yêu cầu Bạn đã vượt quá giới hạn yêu cầu hoặc mã thông báo mỗi phút hoặc mỗi giây. Hãy đợi rồi thử lại với thời gian đợi luỹ thừa.
quota_exceeded 429 Quá nhiều yêu cầu Bạn đã vượt quá hạn mức hằng ngày. Đợi đến khi hạn mức được đặt lại hoặc yêu cầu tăng hạn mức.
too_many_requests 429 Quá nhiều yêu cầu Bạn đã đưa ra quá nhiều yêu cầu trong một khoảng thời gian ngắn. Hãy đợi rồi thử lại với thời gian đợi luỹ thừa.
cancelled 499 Ứng dụng đã đóng yêu cầu Ứng dụng khách đã huỷ yêu cầu trước khi yêu cầu hoàn tất. Bạn không cần làm gì cả. Điều này thường có nghĩa là ứng dụng đã ngắt kết nối.
api_error 500 Lỗi máy chủ nội bộ Đã xảy ra lỗi không mong muốn trên máy chủ. Thử gửi lại yêu cầu. Nếu vấn đề vẫn tiếp diễn, hãy liên hệ với nhóm hỗ trợ.
unimplemented 501 Chưa triển khai Thao tác hoặc tính năng này chưa được triển khai hoặc hỗ trợ. Kiểm tra các chức năng của API hoặc chuyển sang một tính năng được hỗ trợ.
service_unavailable 503 Không có dịch vụ Dịch vụ tạm thời bị quá tải hoặc không hoạt động. Hãy đợi rồi thử lại với thời gian đợi luỹ thừa.
deadline_exceeded 504 Hết thời gian chờ của cổng nối Yêu cầu không hoàn tất trong thời hạn. Xoá hoặc tăng chế độ cài đặt thời hạn của ứng dụng để sử dụng chế độ mặc định của máy chủ.

Mã bị chặn tạo

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

Mã Mô tả
safety Lỗi vi phạm về an toàn (nội dung gây hại) đã chặn yêu cầu.
recitation Yêu cầu bị chặn do quy định hạn chế về bản quyền hoặc việc trích dẫn.
language Ngôn ngữ không được hỗ trợ đã chặn yêu cầu.
prohibited_content Nguyên tắc đối với nội dung bị cấm đã chặn yêu cầu này.
spii Các quy định hạn chế về Thông tin nhạy cảm có thể nhận dạng cá nhân đã chặn yêu cầu.
blocklist Các cụm từ bị cấm trong danh sách chặn đã chặn yêu cầu.
image_safety Lỗi vi phạm về an toàn đã chặn quá trình tạo hình ảnh.
image_prohibited_content Nguyên tắc đối với nội dung bị cấm đã chặn việc tạo hình ảnh.
image_recitation Quy định hạn chế về bản quyền hoặc việc trích dẫn đã chặn tính năng tạo hình ảnh.
image_other Quá trình tạo hình ảnh bị chặn vì những lý do không xác định.
content_blocked Một lý do không xác định về chính sách đã chặn yêu cầu.

Mã lỗi tạo

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

Mã Mô tả
malformed_function_call Mô hình đã tạo ra một lệnh gọi hàm không phân tích cú pháp được.
malformed_tool_call Mô hình đã tạo một lệnh gọi công cụ không phân tích cú pháp được.
unexpected_tool_call Mô hình đã gọi một công cụ không được khai báo trong yêu cầu.
no_image Mô hình không tạo được hình ảnh.
too_many_tool_calls Mô hình đã tạo ra nhiều lệnh gọi công cụ hơn mức cho phép.
missing_thought_signature Phản hồi thiếu chữ ký bắt buộc của suy nghĩ.

Đị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'."
  }
}
Trường Loại Mô tả
code chuỗi Mã lỗi mà máy có thể đọc được trong snake_case.
message chuỗi Nội dung mô tả mà con người có thể đọc được về vấn đề đã xảy ra.

Cách gửi lỗi

API gửi lỗi theo cách khác nhau tuỳ thuộc vào việc bạn đưa ra 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 tiêu 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 phát 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ấu trúc code và message tương tự:

{
  "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