Trang này được dịch bởi Cloud Translation API.

Xử lý lỗi API

API Lịch trả về hai cấp độ thông tin lỗi:

Mã lỗi HTTP và thông báo trong tiêu đề
Đối tượng JSON trong nội dung phản hồi có các thông tin bổ sung có thể giúp bạn xác định cách xử lý lỗi.

Phần còn lại của trang này cung cấp tài liệu tham khảo về các lỗi Lịch cùng một số hướng dẫn về cách xử lý các lỗi đó trong ứng dụng của bạn.

Triển khai thuật toán thời gian đợi luỹ thừa

Tài liệu về API Cloud có nội dung giải thích rõ ràng về thời gian đợi luỹ thừa và cách sử dụng thuật toán này với các API của Google.

Lỗi và hành động được đề xuất

Phần này cung cấp bản trình bày JSON đầy đủ về từng lỗi được liệt kê và các hành động đề xuất bạn có thể thực hiện để xử lý lỗi.

400: Yêu cầu không hợp lệ

Lỗi người dùng. Điều này có thể có nghĩa là bạn chưa cung cấp trường hoặc tham số bắt buộc, giá trị được cung cấp không hợp lệ hoặc tổ hợp các trường đã cung cấp không hợp lệ.

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

Hành động đề xuất: Vì đây là lỗi vĩnh viễn, bạn không nên thử lại. Hãy đọc thông báo lỗi và điều chỉnh yêu cầu cho phù hợp.

401: Thông tin xác thực không hợp lệ

Tiêu đề uỷ quyền không hợp lệ. Mã truy cập bạn đang sử dụng đã hết hạn hoặc không hợp lệ.

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

Hành động đề xuất:

Nhận mã truy cập mới bằng mã làm mới dài hạn.
Nếu quá trình này không thành công, hãy hướng người dùng thông qua quy trình OAuth, như mô tả trong bài viết Uỷ quyền cho yêu cầu bằng OAuth 2.0.
Nếu bạn thấy trạng thái này đối với một tài khoản dịch vụ, hãy kiểm tra để đảm bảo rằng bạn đã hoàn tất thành công tất cả các bước trên trang tài khoản dịch vụ.

403: Đã vượt quá giới hạn tốc độ người dùng

Đã đạt đến một trong các giới hạn từ Developer Console.

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

Hành động đề xuất:

Hãy đảm bảo ứng dụng của bạn tuân theo các phương pháp hay nhất trong phần quản lý hạn mức.
Tăng hạn mức trên mỗi người dùng trong dự án Developer Console.
Nếu một người dùng thay mặt nhiều người dùng của một tài khoản Google Workspace đưa ra nhiều yêu cầu, hãy cân nhắc sử dụng một tài khoản dịch vụ có tính năng uỷ quyền trên toàn miền và đặt tham số quotaUser.
Dùng thuật toán thời gian đợi luỹ thừa.

403: Đã vượt quá giới hạn tốc độ

Người dùng đã đạt đến tỷ lệ yêu cầu tối đa của API Lịch Google trên mỗi lịch hoặc trên mỗi người dùng đã xác thực.

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

Hành động đề xuất: Lỗi rateLimitExceeded có thể trả về mã lỗi 403 hoặc 429. Hiện tại, các lỗi này có chức năng tương tự nhau và cần được phản hồi theo cách tương tự bằng cách sử dụng tính năng thời gian đợi luỹ thừa. Ngoài ra, hãy đảm bảo ứng dụng của bạn tuân theo các phương pháp hay nhất trong việc quản lý hạn mức.

403: Đã vượt quá giới hạn sử dụng Lịch

Người dùng đã đạt đến một trong các giới hạn hiện có của Lịch Google để bảo vệ người dùng và cơ sở hạ tầng của Google khỏi hành vi sai trái.

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

Hành động đề xuất:

Hãy đọc thêm về hạn mức sử dụng Lịch trong phần Trợ giúp dành cho quản trị viên Google Workspace.

403: Cấm người không tổ chức

Yêu cầu cập nhật sự kiện đang cố gắng đặt một trong các thuộc tính sự kiện được chia sẻ trong một bản sao không phải của người tổ chức. Chỉ người tổ chức mới có thể đặt các thuộc tính dùng chung (ví dụ: guestsCanInviteOthers, guestsCanModify hoặc 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."
 }
}

Hành động đề xuất:

Nếu bạn đang sử dụng Sự kiện: chèn, Sự kiện: nhập hoặc Sự kiện: cập nhật và yêu cầu của bạn không bao gồm bất kỳ thuộc tính dùng chung nào, điều này tương đương với việc cố gắng đặt sự kiện thành giá trị mặc định. Thay vào đó, hãy cân nhắc sử dụng Events: patch (Sự kiện: bản vá).
Nếu yêu cầu của bạn có các thuộc tính dùng chung, hãy đảm bảo rằng bạn chỉ đang cố gắng thay đổi các thuộc tính này nếu bạn đang cập nhật bản sao của người tổ chức.

404: Không tìm thấy

Không tìm thấy tài nguyên được chỉ định. Lỗi này có thể xảy ra trong một số trường hợp. Sau đây là một số ví dụ:

khi tài nguyên được yêu cầu (có mã nhận dạng được cung cấp) chưa từng tồn tại
khi truy cập vào lịch mà người dùng không truy cập được

{ "error": { " errors": [ { "domain": "global", "reason": "notFound", "message": "Không tìm thấy" } ], "code": 404, "message": "Không tìm thấy" } }

Hành động đề xuất: Sử dụng tính năng thời gian đợi luỹ thừa.

409: Đã tồn tại giá trị nhận dạng được yêu cầu

Đã tồn tại một thực thể có mã nhận dạng được cung cấp trong bộ nhớ.

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

Hành động đề xuất: Tạo mã nhận dạng mới nếu bạn muốn tạo một thực thể mới, nếu không, hãy sử dụng lệnh gọi phương thức update.

410: Đã qua

Các tham số syncToken hoặc updatedMin không còn hợp lệ. Lỗi này cũng có thể xảy ra nếu một yêu cầu cố gắng xoá một sự kiện đã bị xoá.

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

hoặc

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

hoặc

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

Hành động đề xuất: Đối với các tham số syncToken hoặc updatedMin, hãy xoá sạch cửa hàng rồi đồng bộ hoá lại. Để biết thêm thông tin chi tiết, hãy xem phần Đồng bộ hoá tài nguyên hiệu quả. Đối với những sự kiện đã xoá, bạn không cần làm gì thêm.

412: Điều kiện tiên quyết bị lỗi

Etag được cung cấp trong tiêu đề If-match không còn tương ứng với etag hiện tại của tài nguyên.

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

Hành động được đề xuất: Tìm nạp lại thực thể và áp dụng lại các thay đổi. Để biết thêm thông tin chi tiết, hãy xem phần Tải các phiên bản tài nguyên cụ thể.

429: Quá nhiều yêu cầu

Lỗi rateLimitExceeded xảy ra khi người dùng gửi quá nhiều yêu cầu trong một khoảng thời gian nhất định.

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

500: Lỗi phụ trợ

Đã xảy ra lỗi không mong muốn khi xử lý yêu cầu.

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

Hành động đề xuất: Sử dụng tính năng thời gian đợi luỹ thừa.