API Gmail 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 chi tiết bổ sung có thể giúp bạn xác định cách xử lý lỗi.
Ứng dụng Gmail cần nắm bắt và xử lý tất cả các lỗi có thể gặp phải khi sử dụng API REST. Hướng dẫn này cung cấp cho bạn thông tin về cách giải quyết các lỗi cụ thể về 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 các lỗi sau đây trong mã của bạn:
- Bạn chưa cung cấp 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 đã cung cấp không hợp lệ.
- Tệp đính kèm không hợp lệ.
Dưới đây là ví dụ minh hoạ JSON về 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 mà 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ể do thiếu uỷ quyền cho các phạm vi được yêu cầu. Dưới đây là cách biểu diễn 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 dài hạn. Nếu bạn đang sử dụng thư viện ứng dụng, thư viện đó sẽ tự động xử lý việc làm mới mã thông báo. Nếu quá trình này không thành công, hãy hướng dẫn người dùng thông qua quy trình OAuth, như mô tả trong phần Cấp quyền cho ứng dụng của bạn 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 đã vượt quá giới hạn sử dụng hoặc người dùng không có đặ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 số lượng người dùng.
- Đã vượt quá giới hạn tốc độ dự án.
- Bạn không thể sử dụng ứng dụng của mình 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á giới hạn hàng ngày
Lỗi dailyLimitExceeded cho biết đã đạt đến giới hạn API ưu đãi cho dự án của bạn. Dưới đây là cách biểu diễn 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 hạn mức bổ sung.
Để 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 độ 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à cách biểu diễn dưới dạng 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 cố gắng tối ưu hoá mã xử lý ứ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ác yêu cầu thử lại, 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ỷ lệ yêu cầu tối đa của API Gmail. Giới hạn này sẽ khác nhau tuỳ thuộc vào loại yêu cầu.
Dưới đây là cách biểu diễn 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à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.
Khắc phục lỗi 403: Không dùng được ứng dụng có mã ứng 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à cách trình bày 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 vào ứng dụng.
Giải quyết lỗi 429: Quá nhiều yêu cầu
Lỗi "Quá nhiều yêu cầu" 429 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 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 của mỗi người dùng. Sau đây là thông tin về mỗi giới hạn. Tuy nhiên, bạn có thể giải quyết từng giới hạn bằng cách cố gắng thử 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ý cho nhiều tài khoản Gmail. Bạn không được tăng giới hạn 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.
Hạn mức gửi thư
API Gmail thực thi các giới hạn gửi thư tiêu chuẩn hằng ngày. Những giới hạn này sẽ khác nhau đối với người dùng Google Workspace trả tiền 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 của Gmail trong Google Workspace.
Những giới hạn này là dành cho mỗi người dùng và được tất cả các ứng dụng của người dùng chia sẻ, cho dù ứng dụng API, ứng dụng gốc/web hay MSA của SMTP. Nếu vượt quá các giới hạn này, lỗi "Đã vượt quá giới hạn tốc độ người dùng" HTTP 429 Too Many Requests "(Gửi thư)" sẽ được trả về kèm theo 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.
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ể phải mất vài phút để 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 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, nhưng độc lập với IMAP. Những giới hạn này được áp dụng chung trên tất cả ứng dụng API của Gmail đối với một người dùng cụ thể.
Các giới hạn này thường chỉ đạt đến trong các trường hợp đặc biệt hoặc lạm dụng.
Nếu các giới hạn này vượt quá, lỗi "Vượt quá giới hạn tốc độ người dùng" HTTP 429 Too Many Requests
sẽ được trả về và có 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 yêu cầu đồng thời trên mỗi người dùng (ngoài giới hạn tỷ lệ mỗi người dùng). Giới hạn này được dùng chung cho tất cả các ứng dụng API Gmail truy cập vào một người dùng nhất định và đảm bảo rằng không có ứng dụng API nào đang làm quá tải hộp thư của người dùng Gmail hoặc máy chủ phụ trợ của họ.
Việc thực hiện 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 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 đồng thời vào hộp thư của người dùng Gmail cũng có thể gây ra lỗi này. Nếu giới hạn này vượt quá HTTP 429 Too Many Requests
Lỗi "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ụ 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 500 lỗi:
- 502 Cổng vào không hợp lệ
- 503 Không có dịch vụ
- 504 Hết thời gian chờ cổng vào
Thử lại các yêu cầu không thành công để khắc phục lỗi
Bạn có thể định kỳ thử lại một yêu cầu không thành công trong một khoảng thời gian tăng dần để xử lý các lỗi liên quan đến giới hạn số lượng yêu cầu, 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 một giây, sau đó sau 2 giây và sau đó là 4 giây. Phương thức này được gọi là thuật toán thời gian đợi luỹ thừa và dùng để cải thiện mức sử dụng băng thông và tối đa hoá công suất của các 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 1 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ô
Bạn nên sử dụng tính năng phân lô. Tuy nhiên, các kích thước lô lớn hơn có khả năng sẽ kích hoạt giới hạn tốc độ. Bạn không nên gửi các lô lớn 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 bài viết Gửi yêu cầu theo lô.