จัดการข้อผิดพลาดของ API

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

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

เนื้อหาที่เหลือในหน้านี้จะแสดงข้อผิดพลาดของปฏิทิน บางรายการ คําแนะนําเกี่ยวกับวิธีจัดการอุปสรรคในแอป

ใช้ Exponential Backoff

เอกสารประกอบเกี่ยวกับ Cloud APIs มีคำอธิบายที่ดีเกี่ยวกับ Exponential Backoff และวิธีใช้งานร่วมกับ API

ข้อผิดพลาดและ การดำเนินการที่แนะนำ

ส่วนนี้แสดงแทน JSON ที่สมบูรณ์ของแต่ละรายการ การดำเนินการที่แนะนำที่คุณอาจทำเพื่อจัดการกับข้อผิดพลาด

400: คำขอไม่ถูกต้อง

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

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "timeRangeEmpty",
    "message": "The specified time range is empty.",
    "locationType": "parameter",
    "location": "timeMax",
   }
  ],
  "code": 400,
  "message": "The specified time range is empty."
 }
}

การดำเนินการที่แนะนำ: โปรดอย่าลองอีกครั้งเนื่องจากข้อผิดพลาดนี้เป็นข้อผิดพลาดถาวร โปรดอ่านข้อความแสดงข้อผิดพลาดแทนแล้วเปลี่ยนคำขอให้สอดคล้องกัน

401: ข้อมูลเข้าสู่ระบบไม่ถูกต้อง

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

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

การดำเนินการที่แนะนำ

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

403: เกินขีดจำกัดอัตราคำขอของผู้ใช้

ใช้งานถึงขีดจำกัดจาก Developer Console แล้ว 1 รายการ

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

การดำเนินการที่แนะนำ

403: เกินขีดจำกัดอัตราคำขอ

ผู้ใช้ได้ส่งคำขอถึงจำนวนคำขอสูงสุดต่อปฏิทินของ Google Calendar API แล้ว หรือตามผู้ใช้ที่ตรวจสอบสิทธิ์แล้ว

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

การดำเนินการที่แนะนำ: ข้อผิดพลาด rateLimitExceeded รายการอาจแสดงเป็นข้อผิดพลาด 403 หรือ 429 รหัสข้อผิดพลาด ซึ่งปัจจุบันมีฟังก์ชันคล้ายคลึงกันและควรมีการตอบสนอง ในลักษณะเดียวกัน โดยใช้ Exponential Backoff นอกจากนี้ โปรดตรวจสอบว่าแอปเป็นไปตามแนวทางปฏิบัติแนะนำจาก จัดการโควต้า

403: การใช้งานปฏิทินเกินขีดจำกัด

ผู้ใช้ได้ถึงขีดจำกัดหนึ่งใน Google ปฏิทินที่กำหนดไว้เพื่อปกป้อง Google ผู้ใช้และโครงสร้างพื้นฐาน จากพฤติกรรมการละเมิด

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Calendar usage limits exceeded.",
    "reason": "quotaExceeded"
   }
  ],
  "code": 403,
  "message": "Calendar usage limits exceeded."
 }
}

การดำเนินการที่แนะนำ

403: ต้องห้ามสำหรับผู้ที่ไม่ใช่ผู้จัด

คำขออัปเดตกิจกรรมพยายามตั้งค่าพร็อพเพอร์ตี้กิจกรรมที่แชร์รายการใดรายการหนึ่ง ในสำเนาที่ไม่ใช่ของผู้จัด พร็อพเพอร์ตี้ที่ใช้ร่วมกัน (เช่น guestsCanInviteOthers, guestsCanModify หรือ guestsCanSeeOtherGuests) สามารถ ได้โดยผู้จัดเท่านั้น

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "forbiddenForNonOrganizer",
    "message": "Shared properties can only be changed by the organizer of the event."
   }
  ],
  "code": 403,
  "message": "Shared properties can only be changed by the organizer of the event."
 }
}

การดำเนินการที่แนะนำ

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

404: ไม่พบ

ไม่พบทรัพยากรที่ระบุ ซึ่งอาจเกิดขึ้นได้หลายกรณี ตัวอย่างเช่น

  • เมื่อทรัพยากรที่ขอ (ที่มีรหัสที่ระบุ) ไม่เคยมีอยู่
  • เมื่อเข้าถึงปฏิทินที่ผู้ใช้ไม่สามารถเข้าถึงได้

    { "error": { "ข้อผิดพลาด": [ { "domain": "ทั่วโลก", "reason": "ไม่พบ", "message": "ไม่พบ" } ], "code": 404, "message": "ไม่พบ" } }

การดําเนินการที่แนะนํา: ใช้ Exponential Backoff

409: มีตัวระบุที่ขออยู่แล้ว

มีอินสแตนซ์ที่มีรหัสที่ระบุอยู่ในพื้นที่เก็บข้อมูลแล้ว

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "duplicate",
    "message": "The requested identifier already exists."
   }
  ],
  "code": 409,
  "message": "The requested identifier already exists."
 }
}

การดำเนินการที่แนะนำ สร้างรหัสใหม่หากคุณต้องการสร้างอินสแตนซ์ใหม่ หรือให้ใช้ การเรียกเมธอด update

409: ความขัดแย้ง

รายการแบบกลุ่มภายใน events.batch ไม่สามารถดำเนินการเนื่องจากมีความขัดแย้งในการดำเนินงานกับการดำเนินการอื่นๆ ที่ขอ รายการแบบกลุ่ม

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conflict",
    "message": "Conflict"
   }
  ],
  "code": 409,
  "message": "Conflict"
 }
}

การดำเนินการที่แนะนำ: ยกเว้นรายการที่เสร็จแล้วทั้งหมดและยกเว้นทั้งหมด รายการแบบกลุ่มที่ล้มเหลวและลองแสดงรายการที่เหลืออีกครั้งใน events.batch อื่น หรือการดำเนินการเหตุการณ์เดียวที่เกี่ยวข้อง

410: เสร็จแล้ว

พารามิเตอร์ syncToken หรือ updatedMin ใช้งานไม่ได้อีกต่อไป ข้อผิดพลาดนี้ยัง จะเกิดขึ้นเมื่อคำขอพยายามลบกิจกรรมที่ลบไปแล้ว

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "fullSyncRequired",
    "message": "Sync token is no longer valid, a full sync is required.",
    "locationType": "parameter",
    "location": "syncToken",
    }
  ],
  "code": 410,
  "message": "Sync token is no longer valid, a full sync is required."
 }
}

หรือ

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "updatedMinTooLongAgo",
    "message": "The requested minimum modification time lies too far in the past.",
    "locationType": "parameter",
    "location": "updatedMin",
   }
  ],
  "code": 410,
  "message": "The requested minimum modification time lies too far in the past."
 }
}

หรือ

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "deleted",
    "message": "Resource has been deleted"
   }
  ],
  "code": 410,
  "message": "Resource has been deleted"
 }
}

การดำเนินการที่แนะนำ: สำหรับพารามิเตอร์ syncToken หรือ updatedMin ให้ล้างข้อมูล จัดเก็บและซิงค์อีกครั้ง ดูรายละเอียดเพิ่มเติมได้ที่ ซิงค์ทรัพยากรอย่างมีประสิทธิภาพ แต่หากเป็นกิจกรรมที่ลบไปแล้ว ก็ไม่จำเป็นต้องดำเนินการใดๆ เพิ่มเติม

412: เงื่อนไขที่กำหนดไว้ล่วงหน้าล้มเหลว

eTag ที่ให้ไว้ในส่วนหัว If-match ไม่สอดคล้องกับรายการปัจจุบันแล้ว รูปแท็กของทรัพยากร

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conditionNotMet",
    "message": "Precondition Failed",
    "locationType": "header",
    "location": "If-Match",
    }
  ],
  "code": 412,
  "message": "Precondition Failed"
 }
}

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

429: คำขอมากเกินไป

ข้อผิดพลาด rateLimitExceeded เกิดขึ้นเมื่อผู้ใช้ส่งคำขอมากเกินไปใน ตามระยะเวลาที่กำหนด

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

การดำเนินการที่แนะนำ: ข้อผิดพลาด rateLimitExceeded รายการอาจแสดงเป็นข้อผิดพลาด 403 หรือ 429 รหัสข้อผิดพลาด ซึ่งปัจจุบันมีฟังก์ชันคล้ายคลึงกันและควรมีการตอบสนอง ในลักษณะเดียวกัน โดยใช้ Exponential Backoff นอกจากนี้ โปรดตรวจสอบว่าแอปเป็นไปตามแนวทางปฏิบัติแนะนำจาก จัดการโควต้า

500: ข้อผิดพลาดของแบ็กเอนด์

เกิดข้อผิดพลาดที่ไม่คาดคิดขณะประมวลผลคำขอ

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

การดําเนินการที่แนะนํา: ใช้ Exponential Backoff