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