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

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

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

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

รหัส สถานะ HTTP คำอธิบาย การดำเนินการที่แนะนำ
invalid_request 400 คำขอไม่ถูกต้อง เพย์โหลดคำขอมีรูปแบบไม่ถูกต้องหรือมีพารามิเตอร์ที่ไม่ถูกต้อง ตรวจสอบไวยากรณ์และพารามิเตอร์ของคำขอเทียบกับเอกสารอ้างอิง API
failed_precondition 400 คำขอไม่ถูกต้อง ดำเนินการตามคำขอไม่ได้เนื่องจากไม่เป็นไปตามข้อกำหนดเบื้องต้น (เช่น การเรียกเก็บเงินที่ปิดใช้) ยืนยันสถานะการเรียกเก็บเงินของโปรเจ็กต์หรือข้อกำหนดเบื้องต้นของบัญชี
out_of_range 416 ช่วงที่ขอไม่ถูกต้อง พารามิเตอร์คำขออยู่นอกช่วงที่ถูกต้อง ตรวจสอบค่าและขีดจํากัดของพารามิเตอร์
parameter_unknown 400 คำขอไม่ถูกต้อง คำขอมีพารามิเตอร์ที่ไม่รู้จัก โปรดนำพารามิเตอร์ที่ไม่รู้จักออกแล้วลองอีกครั้ง
authentication 401 ไม่ได้รับอนุญาต คีย์ API ขาดหายไป ไม่ถูกต้อง หรือหมดอายุแล้ว ยืนยันคีย์ API
payment_required 402 ต้องชำระเงิน ยอดเครดิตคงเหลือแบบชำระล่วงหน้าของคุณหมดแล้ว เติมเครดิตลงในบัญชีสำหรับการเรียกเก็บเงิน หรือเปิดการเติมเงินอัตโนมัติ อย่าลองอีกครั้ง: คำขอจะไม่สำเร็จจนกว่าจะมีการเพิ่มเครดิต
permission_denied 403 ต้องห้าม คีย์ API ของคุณไม่มีสิทธิ์สำหรับทรัพยากรนี้ ตรวจสอบสิทธิ์ของคีย์ API และสิทธิ์เข้าถึงโปรเจ็กต์
not_found 404 ไม่พบ ไม่พบทรัพยากรที่ร้องขอ ยืนยันเส้นทางทรัพยากรและพารามิเตอร์
model_not_found 404 ไม่พบ ไม่พบโมเดลที่ระบุ ยืนยันชื่อโมเดลหรือเปลี่ยนไปใช้โมเดลอื่น
already_exists 409 เกิดความขัดแย้ง มีเอนทิตีที่คุณพยายามสร้างอยู่แล้ว ตรวจสอบว่ามีทรัพยากรอยู่แล้วหรือไม่ก่อนที่จะสร้างใหม่
aborted 409 เกิดความขัดแย้ง การดำเนินการถูกยกเลิกเนื่องจากความขัดแย้งหรือการตรวจสอบการทำงานพร้อมกันล้มเหลว ลองส่งคำขออีกครั้งในระดับแอปพลิเคชันที่สูงขึ้น
rate_limit_exceeded 429 มีคำขอมากเกินไป คุณส่งคำขอหรือใช้โทเค็นเกินขีดจำกัดต่อนาทีหรือต่อวินาที รอและลองอีกครั้งโดยใช้ Exponential Backoff
quota_exceeded 429 มีคำขอมากเกินไป คุณใช้งานเกินโควต้าต่อวันแล้ว รอจนกว่าโควต้าจะรีเซ็ตหรือขอเพิ่มโควต้า
too_many_requests 429 มีคำขอมากเกินไป คุณส่งคำขอมากเกินไปในช่วงเวลาสั้นๆ รอและลองอีกครั้งโดยใช้ Exponential Backoff
cancelled 499 คำขอที่ไคลเอ็นต์ปิดการเชื่อมต่อ ไคลเอ็นต์ยกเลิกคำขอก่อนที่จะเสร็จสมบูรณ์ คุณไม่ต้องดำเนินการใดๆ ซึ่งโดยปกติแล้วหมายความว่าไคลเอ็นต์ยกเลิกการเชื่อมต่อ
api_error 500 ข้อผิดพลาดภายในเซิร์ฟเวอร์ เกิดข้อผิดพลาดที่ไม่คาดคิดในเซิร์ฟเวอร์ ลองส่งคำขออีกครั้ง หากยังคงพบปัญหาอยู่ โปรดติดต่อทีมสนับสนุน
unimplemented 501 ไม่มีการใช้งาน การดำเนินการหรือฟีเจอร์นี้ยังไม่ได้ใช้งานหรือรองรับ ตรวจสอบความสามารถของ API หรือเปลี่ยนไปใช้ฟีเจอร์ที่รองรับ
service_unavailable 503 ไม่พร้อมให้บริการ บริการมีการใช้งานมากเกินไปหรือหยุดทำงานชั่วคราว รอและลองอีกครั้งโดยใช้ Exponential Backoff
deadline_exceeded 504 เกตเวย์หมดเวลา คำขอไม่เสร็จสมบูรณ์ภายในกำหนดเวลา นำการตั้งค่ากำหนดเวลาของไคลเอ็นต์ออกหรือเพิ่มการตั้งค่าดังกล่าวเพื่อใช้ค่าเริ่มต้นของเซิร์ฟเวอร์

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

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

รหัส คำอธิบาย
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

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