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

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`

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

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

ตัวอย่าง 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."
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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