Gmail API trả về hai cấp thông tin lỗi:
- 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.
Các ứng dụng Gmail phải nắm bắt và xử lý tất cả lỗi có thể gặp phải khi sử dụng REST API. Hướng dẫn này cung cấp hướng dẫn về cách giải quyết các lỗi cụ thể của API.
Giải quyết lỗi 400: Yêu cầu không hợp lệ
Lỗi này có thể là do những lỗi sau trong mã của bạn:
- Bạn chưa cung cấp một trường hoặc tham số bắt buộc.
- Giá trị được cung cấp hoặc tổ hợp các trường được cung cấp là không hợp lệ.
- Tệp đính kèm không hợp lệ.
Sau đây là một biểu diễn JSON mẫu của 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 đăng nhập không hợp lệ
Lỗi 401 cho biết mã 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 uỷ quyền cho các phạm vi được yêu cầu. Sau đây là biểu diễn dưới dạng JSON của lỗi này:
{
"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ã truy cập bằng mã làm mới có thời hạn sử dụng dài. Nếu bạn đang sử dụng một thư viện ứng dụng, thì thư viện đó 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 của bạn bằng Gmail.
Để biết thêm thông tin về hạn mức của Gmail, hãy tham khảo bài viết Hạn mức sử dụng.
Giải quyết lỗi 403: Đã vượt quá hạn mức sử dụng
Lỗi 403 xảy ra khi bạn vượt quá hạn mức sử dụng hoặc người dùng không có đặc quyền phù hợp. Để 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á hạn mức hằng ngày.
- Đã vượt quá giới hạn về số lượng người dùng.
- Đã vượt quá giới hạn về tốc độ của dự án.
- Ứng dụng của bạn không thể dùng trong miền của người dùng đã xác thực.
Để biết thêm thông tin về hạn mức của Gmail, hãy tham khảo bài viết Hạn mức 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 ưu tiên cho dự án của mình. Sau đây là biểu diễn dưới dạng JSON của lỗi này:
{
"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ề hạn mức của Gmail, hãy tham khảo bài viết Hạn mức sử dụng.
Giải quyết lỗi 403: Đã vượt quá hạn mức người dùng
Lỗi userRateLimitExceeded cho biết bạn đã đạt đến giới hạn trên mỗi người dùng. Sau đây là biểu diễn JSON của lỗi này:
{
"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 thử tối ưu hoá mã ứng dụng để giảm số lượng yêu cầu hoặc thử lại 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ực hiện được để giải quyết lỗi.
Để biết thêm thông tin về hạn mức của Gmail, hãy tham khảo bài viết Hạn mức sử dụng.
Giải quyết lỗi 403: Đã vượt quá giới hạn tần suất
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à biểu diễn dưới dạng JSON của lỗi này:
{
"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ực hiện được.
Để biết thêm thông tin về hạn mức của Gmail, hãy tham khảo bài viết Hạn mức sử dụng.
Giải quyết lỗi 403: Không thể 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. Sau đây là biểu thị 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 này 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.
Giải quyết lỗi 429: Quá nhiều yêu cầu
Lỗi 429 "Too many requests" (Quá nhiều yêu cầu) có thể xảy ra do 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ực hiện lại các yêu cầu không thành công hoặc bằng cách chia nhỏ quy trình xử lý trên nhiều tài khoản Gmail. Hạn mức trên mỗi người dùng không thể tăng vì bất kỳ lý do nào. Để biết thêm thông tin về hạn mức, hãy xem phần Hạn mức sử dụng.
Giới hạn gửi thư
Gmail API áp dụng hạn mức gửi thư hằng ngày tiêu chuẩn. Những giới hạn này khác nhau đối với người dùng trả phí và người dùng gmail.com dùng thử. Để biết các hạn mức này, hãy tham khảo bài viết Hạn mức gửi thư của Gmail trong .
Các hạn mức này áp dụng cho mỗi người dùng và được chia sẻ bởi tất cả cá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 "User-rate limit exceeded" ("Vượt quá hạn mức của người dùng") "(Mail sending)" ("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: 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ề phản hồi lỗi 429. 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 này 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 áp dụng cho tất cả ứng dụng Gmail API của một người dùng nhất định.
Những giới hạn này thường chỉ bị vượt quá 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"User-rate limit exceeded" (Đã vượt quá giới hạn tốc độ của 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
Gmail API áp dụng giới hạn yêu cầu đồng thời cho mỗi người dùng (ngoài giới hạn tốc độ cho mỗi người dùng). Tất cả ứng dụng Gmail API truy cập vào một người dùng nhất định đều phải tuân thủ hạn mức này. Hạn mức này đảm bảo rằng không có ứng dụng API nào gây quá tải cho hộp thư Gmail của người dùng hoặc máy chủ phụ trợ của họ.
Việc đưa ra nhiều yêu cầu song song cho một người dùng hoặc gửi các lô có số lượng lớn yêu cầu 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, hệ thống sẽ trả về lỗi HTTP 429 Too Many Requests"Quá nhiều yêu cầu đồng thời cho người dùng".
Giải quyết lỗi 500: Lỗi trong chương trình phụ trợ
backendError xảy ra khi có lỗi không mong muốn trong quá trình 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ực hiện được. Sau đây là danh sách 500 lỗi:
- 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 nối
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 độ, lưu 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 1 giây, sau đó là 2 giây và sau đó là 4 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 các 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ý theo lô. Tuy nhiên, kích thước lô lớn hơn có thể kích hoạt tính năng giới hạn tốc độ. Bạn không nên gửi các lô có hơn 50 yêu cầu. Để biết thông tin về cách gửi yêu cầu hàng loạt, hãy tham khảo phần Gửi yêu cầu hàng loạt.