แก้ไขข้อผิดพลาด

Gmail API จะแสดงข้อมูลข้อผิดพลาด 2 ระดับ ดังนี้

  • รหัสและข้อความแสดงข้อผิดพลาด HTTP ในส่วนหัว
  • ออบเจ็กต์ JSON ในเนื้อหาการตอบกลับพร้อมรายละเอียดเพิ่มเติมที่จะช่วยคุณกำหนดวิธีจัดการข้อผิดพลาด

แอป Gmail ควรจับและจัดการข้อผิดพลาดทั้งหมดที่อาจพบเมื่อใช้ REST API คู่มือนี้จะแสดงวิธีแก้ไขข้อผิดพลาด API ที่เฉพาะเจาะจง

แก้ไขข้อผิดพลาด 400: คำขอไม่ถูกต้อง

ข้อผิดพลาดนี้อาจเกิดจากข้อผิดพลาดต่อไปนี้ในโค้ด

  • ไม่ได้ระบุฟิลด์หรือพารามิเตอร์ที่จําเป็น
  • ค่าที่ระบุหรือชุดค่าผสมของช่องที่ระบุไม่ถูกต้อง
  • ไฟล์แนบไม่ถูกต้อง

ตัวอย่างการแสดง JSON ของข้อผิดพลาดนี้แสดงอยู่ด้านล่าง

{
  "error": {
    "code": 400,
    "errors": [
      {
        "domain": "global",
        "location": "orderBy",
        "locationType": "parameter",
        "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
        "reason": "badRequest"
      }
    ],
    "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
  }
}

หากต้องการแก้ไขข้อผิดพลาดนี้ ให้ตรวจสอบช่อง message และปรับโค้ดของคุณให้ถูกต้อง

แก้ไขข้อผิดพลาด 401: ข้อมูลเข้าสู่ระบบไม่ถูกต้อง

ข้อผิดพลาด 401 บ่งชี้ว่าโทเค็นการเข้าถึงที่คุณใช้อยู่หมดอายุแล้วหรือไม่ถูกต้อง ข้อผิดพลาดนี้ยังอาจเกิดจากไม่มีการให้สิทธิ์สําหรับขอบเขตที่ขอ ต่อไปนี้คือการแสดง JSON ของข้อผิดพลาดนี้

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization",
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

หากต้องการแก้ไขข้อผิดพลาดนี้ ให้รีเฟรชโทเค็นการเข้าถึงโดยใช้โทเค็นรีเฟรชที่มีอายุการใช้งานยาวนาน หากคุณใช้คลังไคลเอ็นต์ คลังจะจัดการการรีเฟรชโทเค็นโดยอัตโนมัติ หากดำเนินการนี้ไม่สำเร็จ ให้นำผู้ใช้ไปยังขั้นตอนการให้สิทธิ์ OAuth ตามที่อธิบายไว้ในการให้สิทธิ์แอปด้วย Gmail

ดูข้อมูลเพิ่มเติมเกี่ยวกับขีดจำกัดของ Gmail ได้ที่หัวข้อขีดจำกัดการใช้งาน

แก้ไขข้อผิดพลาด 403: ใช้งานเกินขีดจํากัด

ข้อผิดพลาด 403 จะเกิดขึ้นเมื่อการใช้งานเกินขีดจํากัดหรือผู้ใช้ไม่มีสิทธิ์ที่เหมาะสม หากต้องการระบุประเภทข้อผิดพลาดที่เฉพาะเจาะจง ให้ประเมินช่อง reason ของ JSON ที่แสดงผล ข้อผิดพลาดนี้เกิดขึ้นในกรณีต่อไปนี้

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับขีดจำกัดของ Gmail ได้ที่หัวข้อขีดจำกัดการใช้งาน

แก้ไขข้อผิดพลาด 403: เกินขีดจํากัดการใช้งานต่อวัน

ข้อผิดพลาด dailyLimitExceeded บ่งบอกว่ามีการใช้ API แบบไม่คิดค่าบริการสำหรับโปรเจ็กต์ถึงขีดจำกัดแล้ว ต่อไปนี้คือการแสดง JSON ของข้อผิดพลาดนี้

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

วิธีแก้ไขข้อผิดพลาดนี้

  1. ไปที่คอนโซล Google API
  2. เลือกโปรเจ็กต์
  3. คลิกแท็บโควต้า
  4. ขอโควต้าเพิ่มเติม ดูข้อมูลเพิ่มเติมได้ที่ขอโควต้าเพิ่ม

ดูข้อมูลเพิ่มเติมเกี่ยวกับขีดจำกัดของ Gmail ได้ที่หัวข้อขีดจำกัดการใช้งาน

แก้ไขข้อผิดพลาด 403: เกินขีดจำกัดอัตราของผู้ใช้

ข้อผิดพลาด userRateLimitExceeded บ่งบอกว่ามีการส่งคำขอถึงขีดจำกัดต่อผู้ใช้แล้ว ต่อไปนี้คือการแสดง JSON ของข้อผิดพลาดนี้

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
   }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
 }
}

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับขีดจำกัดของ Gmail ได้ที่หัวข้อขีดจำกัดการใช้งาน

แก้ไขข้อผิดพลาด 403: เกินขีดจำกัดของอัตรา

ข้อผิดพลาด rateLimitExceeded บ่งชี้ว่าผู้ใช้ส่งคำขอถึงอัตราการส่งคำขอสูงสุดของ Gmail API แล้ว ขีดจํากัดนี้แตกต่างกันไปตามประเภทคําขอ ต่อไปนี้คือการแสดง JSON ของข้อผิดพลาดนี้

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Rate Limit Exceeded",
    "reason": "rateLimitExceeded",
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

หากต้องการแก้ไขข้อผิดพลาดนี้ ให้ลองส่งคำขอที่ไม่สำเร็จอีกครั้ง

ดูข้อมูลเพิ่มเติมเกี่ยวกับขีดจำกัดของ Gmail ได้ที่หัวข้อขีดจำกัดการใช้งาน

แก้ไขข้อผิดพลาด 403: ใช้แอปที่มีรหัส {appId} ในโดเมนของผู้ใช้ที่ตรวจสอบสิทธิ์แล้วไม่ได้

ข้อผิดพลาด domainPolicy เกิดขึ้นเมื่อนโยบายสำหรับโดเมนของผู้ใช้ไม่อนุญาตให้แอปของคุณเข้าถึง Gmail ต่อไปนี้คือการแสดงผล JSON ของข้อผิดพลาดนี้

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Gmail apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Gmail apps."
  }
}

วิธีแก้ไขข้อผิดพลาดนี้

  1. แจ้งให้ผู้ใช้ทราบว่าโดเมนไม่อนุญาตให้แอปของคุณเข้าถึง Gmail
  2. แจ้งให้ผู้ใช้ติดต่อผู้ดูแลระบบโดเมนเพื่อขอสิทธิ์เข้าถึงแอป

แก้ปัญหาข้อผิดพลาด 429: มีคำขอมากเกินไป

ข้อผิดพลาด 429 "มีคำขอมากเกินไป" อาจเกิดขึ้นเนื่องจากขีดจำกัดต่อผู้ใช้รายวัน (รวมถึงขีดจำกัดการส่งอีเมล) ขีดจำกัดแบนด์วิดท์ หรือขีดจำกัดคำขอพร้อมกันต่อผู้ใช้ ข้อมูลเกี่ยวกับขีดจํากัดแต่ละรายการมีดังนี้ อย่างไรก็ตาม ข้อจำกัดแต่ละข้อสามารถแก้ไขได้โดยการพยายามส่งคำขอที่ดำเนินการไม่สำเร็จอีกครั้ง หรือแยกการประมวลผลไปยังบัญชี Gmail หลายบัญชี ขีดจำกัดต่อผู้ใช้จะเพิ่มไม่ได้ไม่ว่าด้วยเหตุผลใดก็ตาม ดูข้อมูลเพิ่มเติมเกี่ยวกับขีดจํากัดได้ที่ขีดจํากัดการใช้งาน

ขีดจำกัดการส่งอีเมล

Gmail API จะบังคับใช้ขีดจํากัดการส่งอีเมลรายวันมาตรฐาน ขีดจำกัดเหล่านี้จะแตกต่างกันสำหรับ Google Workspace ผู้ใช้ที่ชำระเงินและผู้ใช้ Gmail.com ช่วงทดลองใช้ ดูขีดจำกัดเหล่านี้ได้ที่หัวข้อขีดจำกัดการส่งของ Gmail ใน Google Workspace

ขีดจํากัดเหล่านี้เป็นขีดจํากัดต่อผู้ใช้และจะแชร์โดยไคลเอ็นต์ทั้งหมดของผู้ใช้ ไม่ว่าจะเป็นไคลเอ็นต์ API, ไคลเอ็นต์เนทีฟ/เว็บ หรือ MSA ของ SMTP หากส่งเกินขีดจํากัดเหล่านี้ ระบบจะแสดงข้อผิดพลาด HTTP 429 Too Many Requests "เกินขีดจํากัดอัตราผู้ใช้" "(การส่งอีเมล)" พร้อมเวลาในการลองอีกครั้ง โปรดทราบว่าการเกินขีดจํากัดรายวันอาจทําให้ข้อผิดพลาดประเภทนี้เกิดขึ้นเป็นเวลาหลายชั่วโมงก่อนที่คําขอจะได้รับอนุมัติ

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

ขีดจำกัดแบนด์วิดท์

API มีขีดจำกัดแบนด์วิดท์การอัปโหลดและการดาวน์โหลดต่อผู้ใช้ ซึ่งเท่ากับแต่ไม่ได้เชื่อมโยงกับ IMAP ข้อจำกัดเหล่านี้ใช้ร่วมกันกับไคลเอ็นต์ Gmail API ทั้งหมดสำหรับผู้ใช้รายหนึ่งๆ

โดยปกติแล้วขีดจํากัดเหล่านี้จะเกิดขึ้นเฉพาะในสถานการณ์พิเศษหรือมีการละเมิด หากส่งเกินขีดจํากัดเหล่านี้ ระบบจะแสดงข้อผิดพลาด HTTP 429 Too Many Requests "เกินขีดจํากัดอัตราผู้ใช้" พร้อมเวลาในการลองอีกครั้ง โปรดทราบว่าการเกินขีดจํากัดต่อวันอาจส่งผลให้เกิดข้อผิดพลาดประเภทเหล่านี้เป็นเวลาหลายชั่วโมงก่อนที่คําขอจะได้รับอนุมัติ

คำขอหลายรายการพร้อมกัน

Gmail API จะบังคับใช้ขีดจํากัดคําขอพร้อมกันต่อผู้ใช้ (นอกเหนือจากขีดจํากัดอัตราต่อผู้ใช้) ขีดจํากัดนี้ใช้ร่วมกันโดยไคลเอ็นต์ Gmail API ทั้งหมดที่เข้าถึงผู้ใช้รายหนึ่งๆ และช่วยให้มั่นใจว่าไม่มีไคลเอ็นต์ API ใดใช้ทรัพยากรของกล่องจดหมายผู้ใช้ Gmail หรือเซิร์ฟเวอร์แบ็กเอนด์มากเกินไป

การส่งคำขอหลายรายการพร้อมกันสำหรับผู้ใช้รายเดียวหรือการส่งคำขอแบบเป็นกลุ่มซึ่งมีคำขอจํานวนมากอาจทริกเกอร์ข้อผิดพลาดนี้ นอกจากนี้ ไคลเอ็นต์ API อิสระจำนวนมากที่เข้าถึงกล่องจดหมายของผู้ใช้ Gmail พร้อมกันอาจทริกเกอร์ข้อผิดพลาดนี้ได้ด้วย หากส่งคำขอเกินขีดจำกัดนี้ ระบบจะแสดงข้อผิดพลาด HTTP 429 Too Many Requests "มีคำขอพร้อมกันของผู้ใช้มากเกินไป"

แก้ไขข้อผิดพลาด 500: ข้อผิดพลาดที่แบ็กเอนด์

backendError เกิดขึ้นเมื่อเกิดข้อผิดพลาดที่ไม่คาดคิดขณะประมวลผลคำขอ

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
   }
  ],
  "code": 500,
  "message": "Backend Error"
 }
}

หากต้องการแก้ไขข้อผิดพลาดนี้ ให้ลองส่งคำขอที่ไม่สำเร็จอีกครั้ง ต่อไปนี้เป็นรายการข้อผิดพลาด 500

  • 502 เกตเวย์ไม่ถูกต้อง
  • 503 ไม่พร้อมให้บริการ
  • 504 เกตเวย์หมดเวลา

ลองส่งคำขอที่ไม่สำเร็จอีกครั้งเพื่อแก้ไขข้อผิดพลาด

คุณสามารถลองส่งคําขอที่ไม่สําเร็จอีกครั้งเป็นระยะๆ โดยเพิ่มระยะเวลาเรื่อยๆ เพื่อจัดการข้อผิดพลาดที่เกี่ยวข้องกับขีดจํากัดอัตรา ปริมาณเครือข่าย หรือเวลาในการตอบกลับ เช่น คุณอาจลองส่งคําขอที่ล้มเหลวอีกครั้งหลังจากผ่านไป 1 วินาที จากนั้น 2 วินาที และ 4 วินาที วิธีการนี้เรียกว่าExponential Backoff และใช้เพื่อปรับปรุงการใช้แบนด์วิดท์และเพิ่มปริมาณงานของคำขอในสภาพแวดล้อมแบบพร้อมกันให้สูงสุด

เริ่มระยะเวลาการลองใหม่อย่างน้อย 1 วินาทีหลังจากเกิดข้อผิดพลาด

ดูหรือเปลี่ยนขีดจำกัดการใช้งาน เพิ่มโควต้า

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

  1. หากยังไม่มีบัญชีการเรียกเก็บเงินสำหรับโปรเจ็กต์ ให้สร้างบัญชี
  2. ไปที่หน้า API ที่เปิดใช้ในไลบรารี API ในคอนโซล API แล้วเลือก API จากรายการ
  3. หากต้องการดูและเปลี่ยนการตั้งค่าที่เกี่ยวข้องกับโควต้า ให้เลือกโควต้า หากต้องการดูสถิติการใช้งาน ให้เลือกการใช้งาน

คำขอแบบเป็นกลุ่ม

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