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

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

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

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

สรุปรหัสสถานะ HTTP

รหัสข้อผิดพลาด	คำอธิบาย
200 - OK	คำขอสำเร็จ (นี่คือการตอบกลับมาตรฐานสำหรับคำขอ HTTP ที่สำเร็จ)
400 - Bad Request	เซิร์ฟเวอร์ดำเนินการตามคำขอไม่สำเร็จเนื่องจากเกิดข้อผิดพลาดเกี่ยวกับไคลเอ็นต์
401 - Unauthorized	คำขอมีข้อมูลเข้าสู่ระบบที่ไม่ถูกต้อง
403 - Forbidden	เซิร์ฟเวอร์ได้รับและเข้าใจคำขอ แต่ผู้ใช้ไม่มีสิทธิ์ดำเนินการตามคำขอ
404 - Not Found	ไม่พบทรัพยากรที่ขอ
429 - Too Many Requests	มีคำขอไปยัง API มากเกินไป
500, 502, 503, 504 - Server Errors	เกิดข้อผิดพลาดที่ไม่คาดคิดขณะประมวลผลคำขอ

ข้อผิดพลาด 400

ข้อผิดพลาดเหล่านี้หมายความว่าคำขอมีข้อผิดพลาด ซึ่งมักเกิดจากไม่มีพารามิเตอร์ที่จำเป็น

badRequest

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

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

หมายเหตุ: รายการนี้ไม่ได้แสดงข้อมูลทั้งหมด ปัญหาอื่นๆ อาจทำให้เกิดข้อผิดพลาด 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

ข้อผิดพลาดเหล่านี้หมายความว่าคำขอไม่มีโทเค็นเพื่อการเข้าถึงที่ถูกต้อง

authError

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

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

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

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

ข้อผิดพลาด 403

ข้อผิดพลาดเหล่านี้จะเกิดขึ้นเมื่อคุณใช้งานเกินขีดจำกัดการใช้งาน หรือผู้ใช้ไม่มี สิทธิ์ที่ถูกต้อง หากต้องการหาสาเหตุ ให้ประเมินฟิลด์ reason ของ JSON ที่ส่งคืน ข้อผิดพลาดนี้จะเกิดขึ้นในสถานการณ์ต่อไปนี้

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

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

dailyLimitExceeded

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

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

ข้อผิดพลาดนี้เกิดขึ้นเมื่อเจ้าของแอปพลิเคชันกำหนดโควต้าเพื่อจำกัดการใช้งาน ทรัพยากรหนึ่งๆ หากต้องการแก้ไขข้อผิดพลาดนี้ ให้เพิ่มโควต้าในโปรเจ็กต์ Google Cloud ดูข้อมูลเพิ่มเติมได้ที่จัดการโควต้า ที่จำกัด

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. แจ้งให้ผู้ใช้ติดต่อผู้ดูแลระบบโดเมนเพื่อขอสิทธิ์เข้าถึง แอปของคุณ

rateLimitExceeded

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

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

ลองทำตามขั้นตอนต่อไปนี้เพื่อแก้ไขข้อผิดพลาด

• ขอเพิ่มโควต้า
• ใช้ Exponential Backoff เพื่อลองส่งคำขออีกครั้ง

userRateLimitExceeded

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

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

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

ข้อผิดพลาด 429

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

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

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

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

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

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

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

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

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

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

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

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

ข้อผิดพลาด 500, 502, 503, 504

ข้อผิดพลาดเหล่านี้เกิดขึ้นเมื่อมีข้อผิดพลาดที่ไม่คาดคิดเกี่ยวกับเซิร์ฟเวอร์ขณะประมวลผลคำขอ ข้อผิดพลาดเหล่านี้อาจเกิดจากปัญหาต่างๆ เช่น เวลาของคำขอ ทับซ้อนกับคำขออื่น หรือคำขอสำหรับการดำเนินการที่ไม่รองรับ เช่น พยายามอัปเดตสิทธิ์สำหรับหน้าเดียวใน Google Sites แทน ทั้งเว็บไซต์

รายการข้อผิดพลาด 5xx มีดังนี้

• 500 ข้อผิดพลาดที่แบ็กเอนด์
• 502 เกตเวย์ไม่ถูกต้อง
• 503 ไม่พร้อมให้บริการ
• 504 เกตเวย์หมดเวลา

backendError

ข้อผิดพลาดนี้เกิดขึ้นเมื่อมีข้อผิดพลาดที่ไม่คาดคิดขณะประมวลผลคำขอ ตัวอย่าง JSON ต่อไปนี้แสดงข้อผิดพลาดนี้

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

หากต้องการแก้ไขข้อผิดพลาดนี้ ให้ใช้ Exponential Backoff เพื่อลองส่งคำขออีกครั้ง

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

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

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

จัดการโควต้า

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

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

ดูข้อมูลเพิ่มเติมได้ที่ดูและจัดการ โควต้า

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

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

หัวข้อที่เกี่ยวข้อง

• เคล็ดลับด้านประสิทธิภาพ
• แก้ปัญหาการตรวจสอบสิทธิ์และการให้สิทธิ์