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

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

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

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

รหัส สถานะ HTTP คำอธิบาย การดำเนินการที่แนะนำ
invalid_request 400 คำขอไม่ถูกต้อง เพย์โหลดคำขอมีรูปแบบไม่ถูกต้องหรือมีพารามิเตอร์ที่ไม่ถูกต้อง ตรวจสอบไวยากรณ์และพารามิเตอร์ของคำขอเทียบกับเอกสารอ้างอิง API
failed_precondition 400 คำขอไม่ถูกต้อง ระบบประมวลผลคำขอไม่ได้เนื่องจากไม่เป็นไปตามข้อกำหนดเบื้องต้น (เช่น การเรียกเก็บเงินถูกปิดใช้) ยืนยันสถานะการเรียกเก็บเงินของโปรเจ็กต์หรือข้อกำหนดเบื้องต้นของบัญชี
out_of_range 416 Requested Range Not Satisfiable พารามิเตอร์คำขออยู่นอกช่วงที่ถูกต้อง ตรวจสอบค่าพารามิเตอร์และขีดจำกัด
parameter_unknown 400 คำขอไม่ถูกต้อง คำขอมีพารามิเตอร์ที่ไม่รู้จัก โปรดนำพารามิเตอร์ที่ไม่รู้จักออกแล้วลองอีกครั้ง
authentication 401 ไม่ได้รับอนุญาต ไม่มีคีย์ API, คีย์ API ไม่ถูกต้อง หรือคีย์ API หมดอายุ ยืนยันคีย์ API
payment_required 402 ต้องชำระเงิน ยอดเครดิตคงเหลือแบบชำระเงินล่วงหน้าของคุณหมดแล้ว เพิ่มเครดิตในบัญชีสำหรับการเรียกเก็บเงิน หรือเปิดการเติมเงินอัตโนมัติ อย่าลองอีกครั้ง: คำขอจะไม่สำเร็จจนกว่าจะมีการเพิ่มเครดิต
permission_denied 403 ต้องห้าม คีย์ API ของคุณไม่มีสิทธิ์สำหรับแหล่งข้อมูลนี้ หรือการเข้าถึง API ของโปรเจ็กต์ถูกจำกัด ตรวจสอบสิทธิ์ของคีย์ API, การมีสิทธิ์ตามระดับของโปรเจ็กต์ และสถานะการเรียกเก็บเงิน ดูหัวข้อแก้ปัญหาโปรเจ็กต์ถูกจำกัดหรือไม่พร้อมใช้งาน
not_found 404 Not Found ไม่พบทรัพยากรที่ร้องขอ ยืนยันเส้นทางและพารามิเตอร์ของทรัพยากร
model_not_found 404 Not Found ไม่พบโมเดลที่ระบุ ยืนยันชื่อโมเดลหรือเปลี่ยนไปใช้โมเดลอื่น
already_exists 409 Conflict มีเอนทิตีที่คุณพยายามสร้างอยู่แล้ว ตรวจสอบว่ามีทรัพยากรอยู่แล้วหรือไม่ก่อนสร้างใหม่
aborted 409 Conflict การดำเนินการถูกยกเลิกเนื่องจากความขัดแย้งหรือการตรวจสอบการทำงานพร้อมกันไม่สำเร็จ ลองส่งคำขออีกครั้งที่ระดับแอปพลิเคชันที่สูงขึ้น
rate_limit_exceeded 429 Too Many Requests คุณส่งคำขอหรือใช้โทเค็นเกินขีดจำกัดต่อนาทีหรือต่อวินาทีแล้ว รอและลองอีกครั้งโดยใช้ Exponential Backoff
quota_exceeded 429 Too Many Requests คุณใช้งานเกินโควต้ารายวันแล้ว โปรดรอจนกว่าโควต้าจะรีเซ็ตหรือขอเพิ่มโควต้า
too_many_requests 429 Too Many Requests คุณส่งคำขอมากเกินไปในช่วงเวลาสั้นๆ รอและลองอีกครั้งโดยใช้ 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

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