Xử lý lỗi API

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

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

Bạn nên kiểm thử việc xử lý lỗi của ứng dụng trong môi trường thực.

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

Tài liệu về API đám mây giải thích rõ về thời gian đợi luỹ thừa và cách sử dụng thời gian đợi 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 nội dung đại diện JSON đầy đủ cho từng lỗi được liệt kê và các hành động đề 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. Đ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ị bạn cung cấp không hợp lệ hoặc tổ hợp các trường bạn 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."
 }
}

Thao tác đề xuất: Vì đây là lỗi vĩnh viễn nên bạn không nên thử lại. Thay vào đó, hãy đọc thông báo lỗi và thay đổi yêu cầu của bạn 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ã thông báo 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 nên thực hiện:

• Lấy mã truy cập mới bằng mã làm mới có thời hạn dài.
• Nếu 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 phần Uỷ quyền cho các yêu cầu bằng OAuth 2.0.
• Nếu bạn thấy thông báo này cho một tài khoản dịch vụ, hãy kiểm tra để đảm bảo bạn đã hoàn tất thành công tất cả các bước trong trang tài khoản dịch vụ.

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

Đã đạt đến một trong các giới hạn 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 nên thực hiện:

• Đảm bảo ứng dụng của bạn tuân thủ 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 trên Developers Console.
• Nếu một người dùng thay mặt cho nhiều người dùng của một tài khoản Google Workspace gửi nhiều yêu cầu, hãy cân nhắc sử dụng 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.
• Sử dụng thời gian đợi luỹ thừa.

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

Người dùng đã đạt đến tốc độ 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 mã 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 thời gian đợi luỹ thừa. Ngoài ra, hãy đảm bảo ứng dụng của bạn tuân thủ 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 giới hạn của Lịch Google được áp dụng để 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 nên thực hiện:

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

403: Người không phải là người tổ chức bị cấm

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 dùng chung 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 nên thực hiện:

• 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, 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. Thay vào đó, hãy cân nhắc sử dụng 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. Điều 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ã nhận dạng được cung cấp) chưa bao giờ 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": "Không tìm thấy" } ], "code": 404, "message": "Không tìm thấy" } }

Hành động được đề xuất: Sử dụng 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ã nhận dạng đã 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 đề 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 cập nhật.

409: Xung đột

Không thể thực thi một mục theo lô bên trong thao tác events.batch do xung đột hoạt động với các mục theo 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 đã hoàn tất thành công và tất cả các mục đã hoàn tất không thành công, sau đó 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 đơn 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ệ nữa. Lỗi này cũng có thể xảy ra nếu một yêu cầu tìm cách 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 và đồ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 một cách hiệu quả. Đối với những sự kiện đã bị xoá, bạn không cần làm gì thêm.

412: Điều kiện tiên quyết không được đáp ứng

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 đề 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"
  }
}

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 mã 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 thời gian đợi luỹ thừa. Ngoài ra, hãy đảm bảo ứng dụng của bạn tuân thủ các phương pháp hay nhất trong phần quản lý hạn mức.

500: Lỗi phần phụ trợ

Đã xảy ra lỗi ngoài dự kiến trong 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 thời gian đợi luỹ thừa.