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

หน้านี้แสดงข้อมูลอ้างอิงสำหรับรหัสข้อผิดพลาดของแบ็กเอนด์ที่ API GenerateContent แสดงผล อธิบายรูปแบบการตอบกลับข้อผิดพลาดของ 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
403 PERMISSION_DENIED คีย์ API ของคุณไม่มีสิทธิ์ที่จำเป็น คุณใช้คีย์ API ที่ไม่ถูกต้อง หรือพยายามใช้โมเดลที่ปรับแต่งแล้วโดยไม่ได้ผ่านการตรวจสอบสิทธิ์ที่เหมาะสม ตรวจสอบว่าได้ตั้งค่าคีย์ API และคีย์ API มีสิทธิ์เข้าถึงที่ถูกต้อง และตรวจสอบว่าได้ผ่านการตรวจสอบสิทธิ์ที่เหมาะสมเพื่อใช้โมเดลที่ปรับแต่งแล้ว
404 NOT_FOUND ไม่พบทรัพยากรที่ขอ ไม่พบไฟล์รูปภาพ เสียง หรือวิดีโอที่อ้างอิงในคำขอ ตรวจสอบว่าพารามิเตอร์ทั้งหมดในคำขอใช้ได้กับ API เวอร์ชันของคุณ
429 RESOURCE_EXHAUSTED คุณใช้เกินขีดจำกัดอัตราอย่างน้อย 1 รายการของ API (RPM, TPM, RPD, ค่าใช้จ่าย ฯลฯ) คุณส่งคำขอมากเกินไป ใช้โทเค็นมากเกินไป หรือใช้เกินขีดจำกัดตามค่าใช้จ่ายสำหรับประวัติการเรียกเก็บเงินและระดับของบัญชี ตรวจสอบว่าคุณอยู่ภายในขีดจำกัดอัตราของโมเดล รอสักครู่แล้วลองอีกครั้ง ลดอัตราหรือขนาดของคำขอ ขอเพิ่มขีดจำกัดอัตรา หากจำเป็น
499 CANCELLED การดำเนินการถูกยกเลิก ซึ่งโดยปกติแล้วจะเป็นผู้เรียก ไคลเอ็นต์ปิดการเชื่อมต่อก่อนที่ 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

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