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

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, เนทีฟ/เว็บไคลเอ็นต์ หรือ SMTP MSA หากใช้งานเกินขีดจำกัดเหล่านี้ ระบบจะแสดงข้อผิดพลาด "เกินขีดจำกัดของอัตราผู้ใช้" 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 รายการ ดูข้อมูลเกี่ยวกับวิธีจัดกลุ่มคำขอได้ที่คำขอแบบกลุ่ม