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

หน้านี้มีข้อมูลอ้างอิงสำหรับรหัสข้อผิดพลาดของแบ็กเอนด์ที่ GenerateContent API แสดง อธิบายรูปแบบการตอบกลับข้อผิดพลาดของ gRPC และแสดงขั้นตอนการแก้ปัญหา

รหัสข้อผิดพลาด HTTP

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

รหัส HTTP สถานะ คำอธิบาย ตัวอย่าง Solution
400 INVALID_ARGUMENT เนื้อหาของคำขอมีรูปแบบไม่ถูกต้อง คำขอของคุณมีข้อผิดพลาดในการพิมพ์หรือไม่มีช่องที่ต้องกรอก ดูรูปแบบคำขอ ตัวอย่าง และเวอร์ชันที่รองรับได้ในเอกสารอ้างอิง API การใช้ฟีเจอร์จาก API เวอร์ชันใหม่กว่ากับปลายทางที่เก่ากว่าอาจทำให้เกิดข้อผิดพลาด
400 FAILED_PRECONDITION ระดับฟรีของ Gemini API ไม่พร้อมให้บริการในประเทศของคุณ โปรดเปิดใช้การเรียกเก็บเงินในโปรเจ็กต์ของคุณใน Google AI Studio คุณกำลังส่งคำขอในภูมิภาคที่ไม่รองรับระดับฟรี และคุณยังไม่ได้เปิดใช้การเรียกเก็บเงินในโปรเจ็กต์ใน Google AI Studio หากต้องการใช้ Gemini API คุณจะต้องตั้งค่าแพ็กเกจแบบชำระเงินโดยใช้ Google AI Studio
402 RESOURCE_EXHAUSTED ยอดเครดิตคงเหลือแบบชำระล่วงหน้าของคุณหมดแล้ว บัญชีสำหรับการเรียกเก็บเงินของคุณมีเครดิตแบบชำระล่วงหน้าไม่เพียงพอ ดังนั้นคีย์ API ทุกรายการที่ลิงก์กับบัญชีสำหรับการเรียกเก็บเงินดังกล่าวจะหยุดทำงาน เติมเครดิตลงในบัญชีสำหรับการเรียกเก็บเงิน หรือเปิดการเติมเงินอัตโนมัติ อย่าลองส่งคำขอนี้อีกครั้ง เนื่องจากจะดำเนินการไม่สำเร็จจนกว่าจะมีการเพิ่มเครดิต
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 บริการประมวลผลไม่เสร็จภายในกำหนดเวลา พรอมต์ (หรือบริบท) มีขนาดใหญ่เกินกว่าจะประมวลผลได้ทันเวลา ตั้งค่า "หมดเวลา" ให้ยาวขึ้นในคำขอของไคลเอ็นต์เพื่อหลีกเลี่ยงข้อผิดพลาดนี้

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

เมื่อGenerateContentคำขอไม่สำเร็จ API จะตั้งรหัสสถานะ HTTP (เช่น 400 Bad Request, 403 Forbidden หรือ 429 Too Many Requests) และแสดงผลเนื้อความการตอบกลับ JSON ที่มีรายละเอียดสถานะ gRPC ดังนี้

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
ช่อง ประเภท คำอธิบาย
code จำนวนเต็ม รหัสสถานะ HTTP
message สตริง คำอธิบายข้อผิดพลาดที่มนุษย์อ่านได้
status สตริง รหัสสถานะ gRPC ใน SCREAMING_CASE
details อาร์เรย์ บริบทข้อผิดพลาดเพิ่มเติม เช่น ErrorInfo หรือ LocalizedMessage

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