Xử lý lỗi API

Calendar API trả về thông tin lỗi ở 2 cấp độ:

Mã lỗi và thông báo HTTP trong tiêu đề
Một đối tượng JSON trong nội dung phản hồi có thông tin chi tiết 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 thông tin tham khảo về các lỗi trong Lịch, cùng một số hướng dẫn về cách xử lý các lỗi đó trong ứng dụng.

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

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

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

Phần này cung cấp thông tin đầy đủ về cách biểu diễn JSON của từng lỗi được liệt kê và các hành động được đề xuất mà 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. Lỗi này có thể có nghĩa là một trường hoặc tham số bắt buộc chưa được cung cấp, giá trị được cung cấp không hợp lệ hoặc tổ hợp các trường được 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 được đề xuất: Vì đây là lỗi vĩnh viễn, nên bạn không được thử lại. Thay vào đó, hãy đọc thông báo lỗi và thay đổi yêu cầu cho phù hợp.

401: Thông tin đăng nhập không hợp lệ

Tiêu đề uỷ quyền không hợp lệ. Mã truy cập mà 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 được đề xuất:

Lấy mã truy cập mới bằng mã làm mới tồn tại lâu dài.
Nếu thao tác này không thành công, hãy hướng dẫn người dùng thực hiện quy trình OAuth, như mô tả trong bài viết Cấp quyền cho các yêu cầu bằng OAuth 2.0.
Nếu bạn thấy lỗi này đối với một tài khoản dịch vụ, hãy kiểm tra để đảm bảo bạn đã hoàn tất tất cả các bước trên trang tài khoản dịch vụ.

403: Đã vượt quá hạn mức tần suất gửi của người dùng

Bạn đã đạt đến một trong các hạn mức trong Bảng điều khiển dành cho nhà phát triển.

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

Hành động được đề xuất:

Đả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 cho mỗi người dùng trong dự án Bảng điều khiển dành cho nhà phát triển.
Nếu một người dùng đang thực hiện nhiều yêu cầu thay mặt cho nhiều người dùng của tài khoản Google Workspace, hãy cân nhắc sử dụng tài khoản dịch vụ có cơ chế uỷ quyền trên toàn miền và đặt tham số quotaUser.
Sử dụng thuật toán thời gian đợi luỹ thừa.

403: Đã vượt quá hạn mức tần suất gửi

Người dùng đã đạt đến tỷ lệ yêu cầu tối đa của Google Calendar API cho mỗi lịch hoặc cho 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 được đề xuất: rateLimitExceeded lỗi có thể trả về mã lỗi 403 hoặc 429 mã lỗi—hiện tại, các lỗi này có chức năng tương tự và cần được phản hồi theo cùng một cách, bằng cách sử dụng thuật toán 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 phần quản lý hạn mức.

403: Đã vượt quá hạn mức sử dụng Lịch

Người dùng đã đạt đến một trong các hạn mứ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 được đề xuất:

Đọ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: Bị cấm đối với người không phải là người 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 được chia sẻ (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 được đề 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 được chia sẻ nào, thì điều này tương đương với việc cố gắng đặt các thuộc tính đó thành giá trị mặc định. Hãy cân nhắc sử dụng Sự kiện: vá thay thế.
Nếu yêu cầu của bạn có các thuộc tính được chia sẻ, 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 đ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. Dưới đây là một số ví dụ:

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

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

Hành động được đề xuất: Sử dụng thuật toán thời gian đợi luỹ thừa.

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

Một thực thể có mã đã cho đã tồn tại 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 được đề xuất: Tạo mã 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 cập nhật.

409: Xung đột

Không thể thực thi một mục được phân lô bên trong một events.batch thao tác do xung đột hoạt động với các mục được phân lô khác được yêu cầu.

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

Hành động được đề xuất: Loại trừ tất cả các mục được phân lô đã hoàn tất thành công và tất cả các mục được phân lô chắc chắn không thành công, đồng thời thử lại các mục còn lại trong một events.batch khác hoặc các thao tác sự kiện riêng lẻ tương ứng.

410: Không tồn tại

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 được đề xuất: Đối với các tham số syncToken hoặc updatedMin, hãy xoá bộ nhớ và đồng bộ hoá lại. Để biết thêm thông tin, hãy xem bài viết Đồng bộ hoá tài nguyên một cách hiệu quả. Đối với các sự kiện đã bị xoá, bạn không cần thực hiện thêm hành động nào.

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 hãy xem bài viết Nhận các phiên bản cụ thể của tài nguyên.

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 chương trình 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 được đề xuất: Sử dụng thuật toán thời gian đợi luỹ thừa.

Xử lý lỗi API Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

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

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

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

401: Thông tin đăng nhập không hợp lệ

403: Đã vượt quá hạn mức tần suất gửi của người dùng

403: Đã vượt quá hạn mức tần suất gửi

403: Đã vượt quá hạn mức sử dụng Lịch

403: Bị cấm đối với người không phải là người tổ chức

404: Không tìm thấy

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

409: Xung đột

410: Không tồn tại

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

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

500: Lỗi chương trình phụ trợ

Xử lý lỗi API