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

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

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

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

ทดสอบการจัดการข้อผิดพลาดของแอปพลิเคชันในสภาพแวดล้อมจริง ดูข้อมูลเพิ่มเติม ได้ที่ ทดสอบการจัดการขีดจำกัดโควต้า

ใช้ Exponential Backoff

เอกสารประกอบของ Google Cloud Storage อธิบายเกี่ยวกับ Exponential Backoff และวิธีใช้กับ Google 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: เกินขีดจำกัดอัตราต่อผู้ใช้

ถึงขีดจำกัดรายการใดรายการหนึ่งจากคอนโซล Google Cloud แล้ว

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

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

• ตรวจสอบว่าแอปของคุณเป็นไปตามแนวทางปฏิบัติแนะนำจาก หัวข้อจัดการโควต้า
• เพิ่มโควต้าต่อผู้ใช้ในโปรเจ็กต์คอนโซล
• หากผู้ใช้รายหนึ่งส่งคำขอจำนวนมากในนามของผู้ใช้บัญชี Google Workspace หลายราย ให้พิจารณา ใช้บัญชีบริการที่มีการมอบสิทธิ์ทั่วทั้งโดเมน และตั้งค่าพารามิเตอร์ quotaUser
• ใช้ Exponential Backoff

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

ผู้ใช้ส่งคำขอถึงอัตราคำขอสูงสุดของ 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 จากพฤติกรรมที่ไม่เหมาะสม

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

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

• อ่านข้อมูลเพิ่มเติมเกี่ยวกับขีดจำกัดการใช้งานปฏิทินใน ศูนย์ช่วยเหลือของผู้ดูแลระบบ Google Workspace

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."
  }
}

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

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

404: ไม่พบ

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

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

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "Not Found"
      }
    ],
    "code": 404,
    "message": "Not Found"
  }
}

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

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

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

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

การดำเนินการที่แนะนำ: สร้างรหัสใหม่หากต้องการสร้างอินสแตนซ์ใหม่ หรือใช้เมธอด events.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 ไม่ตรงกับ ETag ปัจจุบันของทรัพยากรอีกต่อไป

{
  "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