API Gmail 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.
Ứng dụng Gmail phải phát hiện và xử lý tất cả lỗi có thể gặp phải khi sử dụng API REST. Hướng dẫn này cung cấp hướng dẫn về cách khắc phục các lỗi API cụ thể.
Giải quyết lỗi 400: Yêu cầu không hợp lệ
Lỗi này có thể là do các lỗi sau trong mã:
- Bạn chưa cung cấp một trường hoặc tham số bắt buộc.
- Giá trị đã cung cấp hoặc tổ hợp các trường đã cung cấp là không hợp lệ.
- Tệp đính kèm không hợp lệ.
Sau đây là nội dung JSON mẫu thể hiện lỗi này:
{
"error": {
"code": 400,
"errors": [
{
"domain": "global",
"location": "orderBy",
"locationType": "parameter",
"message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
"reason": "badRequest"
}
],
"message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
}
}
Để khắc phục lỗi này, hãy kiểm tra trường message và điều chỉnh mã cho phù hợp.
Giải quyết lỗi 401: Thông tin xác thực không hợp lệ
Lỗi 401 cho biết 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ệ. Lỗi này cũng có thể xảy ra do thiếu quyền cho các phạm vi được yêu cầu. Sau đây là nội dung biểu diễn lỗi này ở định dạng JSON:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "authError",
"message": "Invalid Credentials",
"locationType": "header",
"location": "Authorization",
}
],
"code": 401,
"message": "Invalid Credentials"
}
}
Để khắc phục lỗi này, hãy làm mới mã thông báo truy cập bằng mã thông báo làm mới có thời gian tồn tại lâu dài. Nếu bạn đang sử dụng thư viện ứng dụng, thư viện này sẽ tự động xử lý việc làm mới mã thông báo. 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 ứng dụng bằng Gmail.
Để biết thêm thông tin về các giới hạn của Gmail, hãy tham khảo bài viết Giới hạn sử dụng.
Giải quyết lỗi 403: Đã vượt quá giới hạn sử dụng
Lỗi 403 xảy ra khi bạn vượt quá giới hạn sử dụng hoặc người dùng không có quyền chính xác. Để xác định loại lỗi cụ thể, hãy đánh giá trường reason của JSON được trả về. Lỗi này xảy ra trong các trường hợp sau:
- Đã vượt quá giới hạn hằng ngày.
- Đã vượt quá giới hạn tần suất gửi của người dùng.
- Đã vượt quá giới hạn tốc độ của dự án.
- Không thể sử dụng ứng dụng của bạn trong miền của người dùng đã xác thực.
Để biết thêm thông tin về các giới hạn của Gmail, hãy tham khảo bài viết Giới hạn sử dụng.
Giải quyết lỗi 403: Vượt quá hạn mức hằng ngày
Lỗi dailyLimitExceeded cho biết bạn đã đạt đến giới hạn API miễn phí cho dự án. Sau đây là nội dung biểu diễn lỗi này ở định dạng JSON:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "dailyLimitExceeded",
"message": "Daily Limit Exceeded"
}
],
"code": 403,
"message": "Daily Limit Exceeded"
}
}
Cách khắc phục lỗi này:
- Truy cập vào Google API Console
- Chọn dự án của bạn.
- Nhấp vào thẻ Hạn mức
- Yêu cầu hạn mức bổ sung. Để biết thêm thông tin, hãy xem phần Yêu cầu thêm hạn mức.
Để biết thêm thông tin về các giới hạn của Gmail, hãy tham khảo bài viết Giới hạn sử dụng.
Khắc phục lỗi 403: Đã vượt quá hạn mức số lượt truy cập của người dùng
Lỗi userRateLimitExceeded cho biết đã đạt đến giới hạn trên mỗi người dùng. Sau đây là nội dung biểu diễn lỗi này ở định dạng JSON:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "userRateLimitExceeded",
"message": "User Rate Limit Exceeded"
}
],
"code": 403,
"message": "User Rate Limit Exceeded"
}
}
Để khắc phục lỗi này, hãy cố gắng tối ưu hoá mã ứng dụng để gửi ít yêu cầu hơn hoặc thử lại các yêu cầu. Để biết thông tin về cách thử lại các yêu cầu, hãy tham khảo bài viết Thử lại các yêu cầu không thành công để giải quyết lỗi.
Để biết thêm thông tin về các giới hạn của Gmail, hãy tham khảo bài viết Giới hạn sử dụng.
Giải quyết lỗi 403: Đã vượt quá giới hạn tốc độ
Lỗi rateLimitExceeded cho biết người dùng đã đạt đến tốc độ yêu cầu tối đa của Gmail API. Giới hạn này thay đổi tuỳ thuộc vào loại yêu cầu.
Sau đây là nội dung biểu diễn lỗi này ở định dạng JSON:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Rate Limit Exceeded",
"reason": "rateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Để khắc phục lỗi này, hãy thử lại các yêu cầu không thành công.
Để biết thêm thông tin về các giới hạn của Gmail, hãy tham khảo bài viết Giới hạn sử dụng.
Giải quyết lỗi 403: Không thể sử dụng ứng dụng có mã nhận dạng {appId} trong miền của người dùng đã xác thực
Lỗi domainPolicy xảy ra khi chính sách cho miền của người dùng không cho phép ứng dụng của bạn truy cập vào Gmail. Dưới đây là nội dung đại diện JSON của lỗi này:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "domainPolicy",
"message": "The domain administrators have disabled Gmail apps."
}
],
"code": 403,
"message": "The domain administrators have disabled Gmail apps."
}
}
Cách khắc phục lỗi này:
- Thông báo cho người dùng rằng miền không cho phép ứng dụng của bạn truy cập vào Gmail.
- Hướng dẫn người dùng liên hệ với Quản trị viên miền để yêu cầu quyền truy cập cho ứng dụng của bạn.
Khắc phục lỗi 429: Quá nhiều yêu cầu
Lỗi 429 "Quá nhiều yêu cầu" có thể xảy ra do các giới hạn hằng ngày trên mỗi người dùng (bao gồm cả giới hạn gửi thư), giới hạn băng thông hoặc giới hạn yêu cầu đồng thời trên mỗi người dùng. Sau đây là thông tin về từng hạn mức. Tuy nhiên, bạn có thể giải quyết từng giới hạn bằng cách thử thử lại các yêu cầu không thành công hoặc bằng cách phân tách quá trình xử lý trên nhiều tài khoản Gmail. Bạn không thể tăng hạn mức trên mỗi người dùng vì bất kỳ lý do gì. Để biết thêm thông tin về các giới hạn, hãy xem bài viết Giới hạn sử dụng.
Giới hạn gửi thư
API Gmail thực thi các hạn mức gửi thư tiêu chuẩn hằng ngày. Các giới hạn này khác nhau đối với người dùng trả phí Google Workspace và người dùng dùng thử gmail.com. Đối với các giới hạn này, hãy tham khảo bài viết Giới hạn gửi thư của Gmail trong Google Workspace.
Các giới hạn này là trên mỗi người dùng và được chia sẻ cho tất cả ứng dụng của người dùng, cho dù đó là ứng dụng API, ứng dụng gốc/ứng dụng web hay MSA SMTP. Nếu vượt quá các giới hạn này, lỗi HTTP 429 Too Many Requests "Vượt quá giới hạn tốc độ người dùng" "(Gửi thư)" sẽ được trả về cùng với thời gian để thử lại.
Xin lưu ý rằng việc vượt quá hạn mức hằng ngày có thể dẫn đến các loại lỗi này trong nhiều giờ trước khi yêu cầu được chấp nhận.
Quy trình gửi thư rất phức tạp: sau khi người dùng vượt quá hạn mức, có thể mất vài phút trước khi API bắt đầu trả về 429 phản hồi lỗi. Vì vậy, bạn không thể giả định rằng phản hồi 200 có nghĩa là email đã được gửi thành công.
Giới hạn băng thông
API có giới hạn băng thông tải lên và tải xuống cho mỗi người dùng bằng với IMAP nhưng độc lập với IMAP. Các giới hạn này được chia sẻ trên tất cả ứng dụng Gmail API cho một người dùng nhất định.
Các giới hạn này thường chỉ xảy ra trong các trường hợp đặc biệt hoặc trường hợp sử dụng sai mục đích.
Nếu vượt quá các giới hạn này, lỗi HTTP 429 Too Many Requests "Vượt quá giới hạn tốc độ người dùng" sẽ được trả về cùng với thời gian thử lại.
Xin lưu ý rằng việc vượt quá giới hạn hằng ngày có thể dẫn đến các loại lỗi này trong nhiều giờ trước khi yêu cầu được chấp nhận.
Yêu cầu đồng thời
API Gmail thực thi giới hạn số lượng yêu cầu đồng thời trên mỗi người dùng (ngoài giới hạn tốc độ trên mỗi người dùng). Tất cả ứng dụng API Gmail truy cập vào một người dùng nhất định đều dùng chung giới hạn này và đảm bảo rằng không có ứng dụng API nào đang gây quá tải cho hộp thư của người dùng Gmail hoặc máy chủ phụ trợ của họ.
Việc tạo nhiều yêu cầu song song cho một người dùng hoặc gửi hàng loạt với số lượng yêu cầu lớn có thể kích hoạt lỗi này. Một số lượng lớn ứng dụng API độc lập truy cập vào hộp thư của người dùng Gmail cùng lúc cũng có thể kích hoạt lỗi này. Nếu vượt quá giới hạn này, lỗi HTTP 429 Too Many Requests "Quá nhiều yêu cầu đồng thời cho người dùng" sẽ được trả về.
Giải quyết lỗi 500: Lỗi phần phụ trợ
backendError xảy ra khi một lỗi không mong muốn phát sinh trong khi xử lý yêu cầu.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
Để khắc phục lỗi này, hãy thử lại các yêu cầu không thành công. Sau đây là danh sách các lỗi 500:
- 502 Cổng không hợp lệ
- 503 Không có dịch vụ
- 504 Hết thời gian chờ của cổng
Thử lại các yêu cầu không thành công để giải quyết lỗi
Bạn có thể định kỳ thử lại một yêu cầu không thành công trong khoảng thời gian tăng dần để xử lý các lỗi liên quan đến giới hạn tốc độ, dung lượng mạng hoặc thời gian phản hồi. Ví dụ: bạn có thể thử lại một yêu cầu không thành công sau một giây, sau đó là sau hai giây và sau bốn giây. Phương thức này được gọi là thời gian đợi lũy thừa và được dùng để cải thiện mức sử dụng băng thông cũng như tối đa hoá thông lượng yêu cầu trong các môi trường đồng thời.
Bắt đầu khoảng thời gian thử lại ít nhất một giây sau khi xảy ra lỗi.
Xem hoặc thay đổi hạn mức sử dụng, tăng hạn mức
Để xem hoặc thay đổi hạn mức sử dụng cho dự án hoặc để yêu cầu tăng hạn mức, hãy làm như sau:
- Nếu bạn chưa có tài khoản thanh toán cho dự án của mình, hãy tạo một tài khoản.
- Truy cập trang API đã bật của thư viện API trong Bảng điều khiển API, chọn một API từ danh sách.
- Để xem và thay đổi chế độ cài đặt liên quan đến hạn mức, hãy chọn Hạn mức. Để xem thống kê sử dụng, hãy chọn Mức sử dụng.
Yêu cầu theo lô (Batch)
Bạn nên sử dụng tính năng xử lý hàng loạt, tuy nhiên, kích thước lô lớn hơn có thể kích hoạt giới hạn tốc độ. Bạn không nên gửi hàng loạt yêu cầu lớn hơn 50 yêu cầu. Để biết thông tin về cách tạo yêu cầu hàng loạt, hãy tham khảo phần Yêu cầu hàng loạt.