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

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 บังคับใช้ขีดจำกัดการส่งอีเมลต่อวันตามมาตรฐาน โดยขีดจำกัดเหล่านี้จะแตกต่างกันสำหรับผู้ใช้ ที่ชำระเงินและผู้ใช้ gmail.com ที่อยู่ในช่วงทดลองใช้ สำหรับขีดจำกัดเหล่านี้ โปรดดูขีดจำกัดการส่งของ Gmail ใน

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

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

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

API มีขีดจำกัดแบนด์วิดท์ในการอัปโหลดและดาวน์โหลดต่อผู้ใช้ ซึ่งเท่ากับ IMAP แต่ไม่ขึ้นอยู่กับ 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 Console แล้วเลือก API จากรายการ
  3. หากต้องการดูและเปลี่ยนการตั้งค่าที่เกี่ยวข้องกับโควต้า ให้เลือกโควต้า หากต้องการดู สถิติการใช้งาน ให้เลือกการใช้งาน

คำขอแบบกลุ่ม

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