คู่มือการแก้ปัญหา

ใช้คู่มือนี้เพื่อช่วยในการวินิจฉัยและแก้ไขปัญหาที่พบบ่อยซึ่งเกิดขึ้นเมื่อคุณเรียกใช้ Gemini API คุณอาจพบปัญหาจากบริการแบ็กเอนด์ของ Gemini API หรือ SDK ของไคลเอ็นต์ SDK ไคลเอ็นต์ของเราเป็นโอเพนซอร์สในที่เก็บต่อไปนี้

หากพบปัญหาเกี่ยวกับคีย์ API ให้ตรวจสอบว่าคุณได้ตั้งค่า คีย์ API อย่างถูกต้องตามคู่มือการตั้งค่าคีย์ API

รหัสข้อผิดพลาดของบริการแบ็กเอนด์ของ Gemini API

ตารางต่อไปนี้แสดงรหัสข้อผิดพลาดที่พบบ่อยในแบ็กเอนด์ที่คุณอาจพบ พร้อมคำอธิบายสาเหตุและขั้นตอนการแก้ปัญหา

รหัส HTTP สถานะ คำอธิบาย ตัวอย่าง Solution
400 INVALID_ARGUMENT เนื้อหาของคำขอมีรูปแบบไม่ถูกต้อง คำขอของคุณมีข้อผิดพลาดในการพิมพ์หรือไม่มีช่องที่ต้องกรอก ดูรูปแบบคำขอ ตัวอย่าง และเวอร์ชันที่รองรับได้ในข้อมูลอ้างอิง API การใช้ฟีเจอร์จาก API เวอร์ชันใหม่กว่ากับปลายทางที่เก่ากว่าอาจทำให้เกิดข้อผิดพลาด
400 FAILED_PRECONDITION ระดับฟรีของ Gemini API ไม่พร้อมให้บริการในประเทศของคุณ โปรดเปิดใช้การเรียกเก็บเงินในโปรเจ็กต์ของคุณใน Google AI Studio คุณกำลังส่งคำขอในภูมิภาคที่ไม่รองรับระดับฟรี และคุณยังไม่ได้เปิดใช้การเรียกเก็บเงินในโปรเจ็กต์ใน Google AI Studio หากต้องการใช้ Gemini API คุณจะต้องตั้งค่าแพ็กเกจแบบชำระเงินโดยใช้ Google AI Studio
403 PERMISSION_DENIED คีย์ API ของคุณไม่มีสิทธิ์ที่จำเป็น คุณใช้คีย์ API ที่ไม่ถูกต้อง คุณ พยายามใช้โมเดลที่ปรับแต่งแล้วโดยไม่ได้ผ่านการตรวจสอบสิทธิ์ที่เหมาะสม ตรวจสอบว่าได้ตั้งค่าคีย์ API และมีสิทธิ์เข้าถึงที่ถูกต้อง และอย่าลืมตรวจสอบสิทธิ์อย่างถูกต้องเพื่อใช้โมเดลที่ปรับแต่งแล้ว
404 NOT_FOUND ไม่พบทรัพยากรที่ขอ ไม่พบไฟล์รูปภาพ เสียง หรือวิดีโอที่อ้างอิงในคำขอ ตรวจสอบว่าพารามิเตอร์ทั้งหมดในคำขอใช้ได้กับ API เวอร์ชันของคุณ
429 RESOURCE_EXHAUSTED คุณได้ใช้งานเกินขีดจำกัดอัตราของ API อย่างใดอย่างหนึ่ง (RPM, TPM, RPD, การใช้จ่าย ฯลฯ) คุณส่งคำขอมากเกินไป ใช้โทเค็นมากเกินไป หรือเกินขีดจำกัดตามการใช้จ่ายสำหรับประวัติการเรียกเก็บเงินและระดับของบัญชี ตรวจสอบว่าคุณอยู่ภายในขีดจำกัดอัตราของโมเดล โปรดรอสักครู่แล้วลองอีกครั้ง ลดอัตราหรือขนาดของคำขอ ขอเพิ่มขีดจำกัดอัตราหากจำเป็น
499 ยกเลิกแล้ว การดำเนินการถูกยกเลิก โดยปกติแล้วจะเป็นผู้โทร ไคลเอ็นต์ปิดการเชื่อมต่อก่อนที่ API จะตอบกลับเสร็จ ตรวจสอบว่าไคลเอ็นต์หรือโครงสร้างพื้นฐานของเครือข่ายปิดการเชื่อมต่อก่อนเวลาอันควรหรือไม่ (เช่น เนื่องจากไทม์เอาต์ฝั่งไคลเอ็นต์)
500 ภายใน เกิดข้อผิดพลาดที่ไม่คาดคิดจากทางฝั่ง Google บริบทของข้อมูลที่คุณป้อนยาวเกินไป ตรวจสอบหน้าสถานะ Gemini API เพื่อดูเหตุการณ์ที่กำลังเกิดขึ้น ลดบริบทอินพุตหรือเปลี่ยนไปใช้โมเดลอื่นชั่วคราว (เช่น จาก Gemini 2.5 Pro เป็น Gemini 2.5 Flash) แล้วดูว่าใช้งานได้หรือไม่ หรือรอสักครู่แล้วลองส่งคำขออีกครั้ง หากปัญหายังคงอยู่หลังจากลองอีกครั้ง โปรดรายงานปัญหาโดยใช้ปุ่มส่งความคิดเห็นใน Google AI Studio
503 UNAVAILABLE บริการอาจมีการใช้งานมากเกินไปหรือหยุดทำงานชั่วคราว บริการนี้มีขีดจำกัดชั่วคราว ตรวจสอบหน้าสถานะ Gemini API เพื่อดูเหตุการณ์ที่กำลังเกิดขึ้น สลับไปใช้โมเดลอื่นชั่วคราว (เช่น จาก Gemini 2.5 Pro เป็น Gemini 2.5 Flash) แล้วดูว่าใช้งานได้หรือไม่ หรือรอสักครู่แล้วลองส่งคำขออีกครั้ง หากปัญหายังคงอยู่หลังจากลองอีกครั้ง โปรดรายงานปัญหาโดยใช้ปุ่มส่งความคิดเห็นใน Google AI Studio
504 DEADLINE_EXCEEDED บริการไม่สามารถประมวลผลให้เสร็จสิ้นภายในกำหนดเวลาได้ พรอมต์ (หรือบริบท) มีขนาดใหญ่เกินกว่าจะประมวลผลได้ทันเวลา ตั้งค่า "หมดเวลา" ให้ยาวขึ้นในคำขอของไคลเอ็นต์เพื่อหลีกเลี่ยงข้อผิดพลาดนี้

กลยุทธ์การลองใหม่

หากได้รับข้อผิดพลาดที่ระบุว่าคุณควรลองส่งคำขออีกครั้ง (เช่น 429 RESOURCE_EXHAUSTED หรือ 503 UNAVAILABLE) เราขอแนะนำให้ใช้กลยุทธ์การหยุดชั่วคราวแบบทวีคูณ ซึ่งหมายความว่าคุณจะรอสักครู่ก่อนที่จะลองอีกครั้งเป็นครั้งแรก จากนั้นค่อยๆ เพิ่มเวลารอระหว่างการลองอีกครั้งในครั้งต่อๆ ไป

SDK ไคลเอ็นต์อย่างเป็นทางการสำหรับ Gemini API เช่น Python SDK มีตรรกะการลองใหม่โดยอัตโนมัติพร้อมการถอยแบบทวีคูณโดยค่าเริ่มต้นเพื่อจัดการข้อผิดพลาดชั่วคราว เช่น หมดเวลา ปัญหาเครือข่าย และขีดจำกัดอัตรา (รหัสสถานะ 429 และ 5xx) ตัวอย่างเช่น Python SDK จะลองใหม่โดยอัตโนมัติสำหรับข้อผิดพลาดชั่วคราวสูงสุด 4 ครั้ง โดยมีระยะเวลาหน่วงเริ่มต้นประมาณ 1 วินาทีและระยะเวลาหน่วงสูงสุด 60 วินาที

หากคุณส่งคำขอ REST API โดยตรงหรือปรับแต่งตรรกะการลองใหม่ ให้ทำตามแนวทางปฏิบัติแนะนำต่อไปนี้เพื่อเพิ่มโอกาสที่คำขอจะสำเร็จและป้องกันไม่ให้บริการทำงานหนักเกินไป

  • ใช้ Exponential Backoff: รอสักครู่ก่อนลองอีกครั้งครั้งแรก (เช่น 1 วินาที) จากนั้นเพิ่มการหน่วงเวลาแบบทวีคูณ (เช่น 2 วินาที 4 วินาที 8 วินาที)
  • เพิ่ม Jitter: เพิ่ม "Jitter" แบบสุ่มลงในดีเลย์เพื่อช่วยป้องกันไม่ให้ไคลเอ็นต์ทั้งหมดลองอีกครั้งในเวลาเดียวกัน
  • ลองอีกครั้งเมื่อเกิดข้อผิดพลาดที่เฉพาะเจาะจง: ลองอีกครั้งเฉพาะเมื่อเกิดข้อผิดพลาดชั่วคราว (เช่น 429, 408 หรือ 5xx) อย่าลองอีกครั้งเมื่อเกิดข้อผิดพลาดของไคลเอ็นต์ (เช่น 400 หรือ 403) เนื่องจากข้อผิดพลาดเหล่านี้บ่งบอกถึงปัญหาต่างๆ เช่น คีย์ API ไม่ถูกต้องหรือไวยากรณ์ไม่ถูกต้อง
  • ตั้งค่าการลองใหม่สูงสุด: กำหนดจำนวนครั้งสูงสุดที่พยายามลองใหม่เพื่อป้องกันไม่ให้เกิดลูปที่ไม่มีที่สิ้นสุด

ตรวจสอบการเรียก API เพื่อหาข้อผิดพลาดของพารามิเตอร์โมเดล

ตรวจสอบว่าพารามิเตอร์ของโมเดลอยู่ภายในค่าต่อไปนี้

พารามิเตอร์โมเดล ค่า (ช่วง)
จำนวนผู้สมัคร 1-8 (จำนวนเต็ม)
อุณหภูมิ 0.0-1.0
โทเค็นเอาต์พุตสูงสุด ใช้หน้าโมเดล เพื่อกำหนดจำนวนโทเค็นสูงสุดสำหรับโมเดลที่คุณใช้
TopP 0.0-1.0

นอกเหนือจากการตรวจสอบค่าพารามิเตอร์แล้ว โปรดตรวจสอบว่าคุณใช้เวอร์ชัน API (เช่น /v1 หรือ /v1beta) และ โมเดลที่รองรับฟีเจอร์ที่คุณต้องการอย่างถูกต้อง เช่น หากฟีเจอร์อยู่ในรุ่นเบต้า ฟีเจอร์นั้นจะใช้ได้ใน /v1beta API เวอร์ชันเท่านั้น

ตรวจสอบว่าคุณมีรุ่นที่ถูกต้อง

ตรวจสอบว่าคุณใช้โมเดลที่รองรับซึ่งแสดงอยู่ในหน้าโมเดล

เวลาในการตอบสนองหรือการใช้โทเค็นที่สูงขึ้นด้วยโมเดล 2.5