ข้อผิดพลาดของ API

หน้านี้มีข้อมูลอ้างอิงสำหรับรหัสข้อผิดพลาดทั้งหมดของ Interactions API, อธิบายรูปแบบการตอบกลับข้อผิดพลาด และอธิบายวิธีที่ API แสดงข้อผิดพลาดสำหรับคำขอประเภทต่างๆ

รหัสข้อผิดพลาดมาตรฐานของ API

รหัสข้อผิดพลาดระดับคำขอทั่วไปเหล่านี้สอดคล้องกับรหัสสถานะ HTTP มาตรฐาน ใช้ช่อง code ในตรรกะของแอปพลิเคชันเพื่อจัดการข้อผิดพลาดโดยอัตโนมัติ

รหัส สถานะ HTTP คำอธิบาย การดำเนินการที่แนะนำ
invalid_request 400 Bad Request คำขอมีรูปแบบไม่ถูกต้องหรือมีพารามิเตอร์ที่ไม่ถูกต้อง ตรวจสอบอินพุตกับเอกสารอ้างอิง API
parameter_unknown 400 Bad Request คำขอมีพารามิเตอร์ที่ไม่รู้จัก นำพารามิเตอร์ที่ไม่รู้จักออกแล้วลองอีกครั้ง
authentication 401 ไม่ได้รับอนุญาต ไม่มีคีย์ API หรือคีย์ API ไม่ถูกต้อง ยืนยันคีย์ API
permission_denied 403 ต้องห้าม คีย์ API ของคุณไม่มีสิทธิ์เข้าถึงทรัพยากรนี้ ตรวจสอบสิทธิ์ของคีย์ API และสิทธิ์เข้าถึงโปรเจ็กต์
not_found 404 ไม่พบ ไม่พบทรัพยากรที่ร้องขอ ยืนยันเส้นทางและพารามิเตอร์ของทรัพยากร
model_not_found 404 ไม่พบ ไม่พบโมเดลที่ระบุ ยืนยันชื่อโมเดลหรือกลับไปใช้โมเดลอื่น
rate_limit_exceeded 429 มีคำขอมากเกินไป คุณส่งคำขอหรือใช้โทเค็นเกินขีดจำกัดต่อนาทีหรือต่อวินาที รอแล้วลองอีกครั้งโดยใช้ Exponential Backoff
quota_exceeded 429 มีคำขอมากเกินไป คุณใช้โควต้าประจำวันเกินขีดจำกัดแล้ว รอจนกว่าโควต้าจะรีเซ็ตหรือขอเพิ่มโควต้า
cancelled 499 คำขอที่ไคลเอ็นต์ปิดการเชื่อมต่อ ไคลเอ็นต์ยกเลิกคำขอก่อนที่จะเสร็จสมบูรณ์ คุณไม่ต้องดำเนินการใดๆ โดยปกติแล้วหมายความว่าไคลเอ็นต์ตัดการเชื่อมต่อ
api_error 500 ข้อผิดพลาดภายในเซิร์ฟเวอร์ เกิดข้อผิดพลาดที่ไม่คาดคิดในเซิร์ฟเวอร์ ลองส่งคำขออีกครั้ง หากยังพบปัญหาอยู่ โปรดติดต่อทีมสนับสนุน
service_unavailable 503 ไม่พร้อมให้บริการ บริการไม่พร้อมใช้งานชั่วคราวหรือหยุดทำงาน รอแล้วลองอีกครั้งโดยใช้ Exponential Backoff

รหัสที่บล็อกการสร้าง

รหัสข้อผิดพลาดเหล่านี้บ่งชี้ว่าข้อจำกัดด้านนโยบาย ความปลอดภัย หรือการจำกัดเนื้อหาบล็อกเอาต์พุตของโมเดล เมื่อได้รับรหัสใดรหัสหนึ่งต่อไปนี้ ให้แก้ไขอินพุตแล้วลองอีกครั้ง

รหัส คำอธิบาย
safety การละเมิดด้านความปลอดภัย (เนื้อหาที่เป็นอันตราย) บล็อกคำขอ
recitation ข้อจำกัดด้านลิขสิทธิ์หรือการท่องจำบล็อกคำขอ
language ภาษาที่ไม่รองรับบล็อกคำขอ
prohibited_content หลักเกณฑ์เกี่ยวกับเนื้อหาที่ไม่อนุญาตบล็อกคำขอ
spii ข้อจำกัดเกี่ยวกับข้อมูลส่วนบุคคลที่ละเอียดอ่อนและระบุตัวบุคคลนั้นได้บล็อกคำขอ
blocklist คำที่ไม่อนุญาตในรายการที่ถูกบล็อกบล็อกคำขอ
image_safety การละเมิดด้านความปลอดภัยบล็อกการสร้างรูปภาพ
image_prohibited_content หลักเกณฑ์เกี่ยวกับเนื้อหาที่ไม่อนุญาตบล็อกการสร้างรูปภาพ
image_recitation ข้อจำกัดด้านลิขสิทธิ์หรือการท่องจำบล็อกการสร้างรูปภาพ
image_other เหตุผลที่ไม่ได้ระบุบล็อกการสร้างรูปภาพ
content_blocked เหตุผลด้านนโยบายที่ไม่ได้ระบุบล็อกคำขอ

รหัสข้อผิดพลาดในการสร้าง

รหัสข้อผิดพลาดเหล่านี้บ่งชี้ว่ามีปัญหาเชิงโครงสร้างกับเอาต์พุตที่สร้างขึ้นของโมเดล (เช่น การเรียกใช้ฟังก์ชันที่มีรูปแบบไม่ถูกต้องหรือการเรียกใช้เครื่องมือที่ไม่ได้ประกาศ)

รหัส คำอธิบาย
malformed_function_call โมเดลสร้างการเรียกใช้ฟังก์ชันที่แยกวิเคราะห์ไม่ได้
malformed_tool_call โมเดลสร้างการเรียกใช้เครื่องมือที่แยกวิเคราะห์ไม่ได้
unexpected_tool_call โมเดลเรียกใช้เครื่องมือที่ไม่ได้ประกาศไว้ในคำขอ
no_image โมเดลสร้างรูปภาพไม่ได้
too_many_tool_calls โมเดลสร้างการเรียกใช้เครื่องมือมากกว่าที่อนุญาต
missing_thought_signature การตอบกลับไม่มีลายเซ็นความคิดที่จำเป็น

รูปแบบการตอบกลับข้อผิดพลาด

ข้อผิดพลาดทั้งหมดจาก Interactions API จะแสดงผลออบเจ็กต์ error ที่มี code และ message เช่น การส่งประเภทเครื่องมือที่ไม่รองรับจะแสดงผลดังนี้

{
  "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'."
  }
}
ช่อง ประเภท คำอธิบาย
code สตริง รหัสข้อผิดพลาดที่เครื่องอ่านได้ในรูปแบบ snake_case
message สตริง คำอธิบายที่มนุษย์อ่านได้เกี่ยวกับสิ่งที่ผิดพลาด

วิธีแสดงข้อผิดพลาด

API จะแสดงข้อผิดพลาดแตกต่างกันไปตามว่าคุณส่งคำขอ HTTP มาตรฐานหรือคำขอสตรีมมิง (SSE)

คำขอ HTTP มาตรฐาน

สำหรับคำขอมาตรฐาน (ที่ไม่ใช่การสตรีมมิง) API จะตั้งรหัสสถานะการตอบกลับ HTTP (เช่น 400 Bad Request, 401 Unauthorized หรือ 429 Too Many Requests) และแสดงผลออบเจ็กต์ error ในเนื้อความการตอบกลับ JSON ดังนี้

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

คำขอสตรีมมิง (SSE)

สำหรับคำขอสตรีมมิง (stream: true) API จะส่งเหตุการณ์ข้อผิดพลาดผ่านสตรีม Server-Sent Events (SSE) โดยตั้งค่า event_type เป็น "error" ช่อง error มีโครงสร้าง code และ message เหมือนกัน ดังนี้

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

ดูสคีมาเหตุการณ์ SSE ทั้งหมดได้ที่เอกสารอ้างอิง Interactions API

ขั้นตอนถัดไป