Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Giải quyết lỗi

Gmail API trả về 2 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 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 của bạn phải phát hiện và xử lý tất cả các lỗi mà bạn 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 giải quyết các lỗi cụ thể của Gmail API.

Tóm tắt mã trạng thái HTTP

Mã lỗi	Mô tả
`200 - OK`	Yêu cầu thành công (đây là phản hồi tiêu chuẩn cho các yêu cầu HTTP thành công).
`400 - Bad Request`	Máy chủ không thực hiện được yêu cầu do lỗi ứng dụng.
`401 - Unauthorized`	Yêu cầu chứa thông tin đăng nhập không hợp lệ.
`403 - Forbidden`	Máy chủ đã nhận và hiểu yêu cầu, nhưng người dùng không có quyền thực hiện yêu cầu.
`404 - Not Found`	Không tìm thấy tài nguyên được yêu cầu.
`429 - Too Many Requests`	Có quá nhiều yêu cầu gửi đến API.
`500, 502, 503, 504 - Server Errors`	Đã xảy ra lỗi ngoài dự kiến trong khi xử lý yêu cầu.

Lỗi 400

Những lỗi này có nghĩa là yêu cầu có lỗi, thường là do thiếu một tham số bắt buộc.

`badRequest`

Lỗi này có thể xảy ra do một trong những vấn đề sau trong mã của bạn:

Thiếu trường hoặc tham số bắt buộc.
Giá trị hoặc tổ hợp trường được cung cấp không hợp lệ.
Tệp đính kèm không hợp lệ.

Mẫu JSON sau đây là một biểu thị 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.

Lỗi 401

Những lỗi này có nghĩa là yêu cầu không chứa mã truy cập hợp lệ.

`authError`

Lỗi này xảy ra khi mã truy cập bạn đang sử dụng đã hết hạn hoặc không hợp lệ. Việc thiếu quyền uỷ quyền cho các phạm vi được yêu cầu cũng có thể gây ra lỗi này. Mẫu JSON sau đây là một biểu thị 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 Tìm hiểu về quy trình xác thực và uỷ quyền.

Để biết thêm thông tin về hạn mức của Gmail, hãy xem bài viết Hạn mức sử dụng.

Lỗi 403

Những lỗi này 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 nguyên nhân, 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:

Ứng dụng của bạn không thể được dùng trong miền của người dùng đã xác thực.
Dự án đã vượt quá giới hạn hằng ngày.
Người dùng đã vượt quá giới hạn tần suất.
Dự án đã vượt quá giới hạn tần suất.

Để biết thêm thông tin, hãy xem phần Hạn mức sử dụng.

`dailyLimitExceeded`

Lỗi này xảy ra khi dự án của bạn đạt đến giới hạn API. Mẫu JSON sau đây là một biểu thị của lỗi này:

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

Lỗi này xảy ra khi chủ sở hữu ứng dụng đặt hạn mức để giới hạn mức sử dụng một tài nguyên cụ thể. Để khắc phục lỗi này, hãy tăng hạn mức trong dự án trên đám mây của Google Cloud. Để biết thêm thông tin, hãy xem bài viết Quản lý hạn mức.

`domainPolicy`

Lỗi này 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. JSON sau đây là biểu thị 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."
  }
}

Để khắc phục lỗi này, hãy thử các bước sau:

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 của họ để yêu cầu cấp quyền truy cập cho ứng dụng của bạn.

`rateLimitExceeded`

Lỗi này cho biết người dùng đã đạt đến tốc độ yêu cầu tối đa cho Gmail API. Giới hạn này thay đổi tuỳ thuộc vào loại yêu cầu. Mẫu JSON sau đây là một biểu thị 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ử các bước sau:

Yêu cầu tăng hạn mức.
Sử dụng thuật toán thời gian đợi luỹ thừa để thử lại yêu cầu.

`userRateLimitExceeded`

Lỗi này xảy ra khi một yêu cầu đạt đến giới hạn trên mỗi người dùng. Mẫu JSON sau đây là một biểu thị 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ã xử lý ứng dụng để đưa ra ít yêu cầu hơn hoặc sử dụng thuật toán thời gian đợi luỹ thừa để thử lại yêu cầu.

Lỗi 429

Lỗi 429 "Quá nhiều yêu cầu" có thể xảy ra do hạn mức hằng ngày cho mỗi người dùng (bao gồm cả hạn mức gửi thư), hạn mức băng thông hoặc hạn mức yêu cầu đồng thời cho 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ử 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.

Bạn không thể tăng hạn mức cho mỗi người dùng. Để 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. Các giới hạn này khác nhau đối với người dùng Google Workspace có tính 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 Google Workspace.

Các giới hạn 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 tích hợp sẵn hay ứng dụng web, hoặc MSA SMTP. Nếu bạn vượt quá các giới hạn này, API sẽ trả về lỗi HTTP 429 "Quá nhiều yêu cầu: Vượt quá giới hạn tốc độ của người dùng (Gửi thư)" kèm theo thời gian thử lại. Việc vượt quá hạn mức hằng ngày có thể dẫn đến những lỗi này trong nhiều giờ trước khi máy chủ chấp nhận yêu cầu.

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ể sẽ mất vài phút trước khi API bắt đầu trả về phản hồi lỗi 429. 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 chia sẻ trên tất cả các ứng dụng Gmail API cho một người dùng.

Người dùng thường chỉ gặp phải những giới hạn này trong các trường hợp đặc biệt hoặc có hành vi sai trái. Nếu bạn vượt quá các giới hạn này, API sẽ trả về lỗi HTTP 429 "Too many requests: User-rate limit exceeded" (Quá nhiều yêu cầu: Vượt quá giới hạn tốc độ của người dùng) kèm theo thời gian thử lại. Việc vượt quá hạn mức hằng ngày có thể dẫn đến những lỗi này trong nhiều giờ trước khi máy chủ chấp nhận yêu cầu.

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 đề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ư của người dùng Gmail 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. Nhiều ứ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 bạn vượt quá giới hạn này, API sẽ trả về lỗi HTTP 429 "Quá nhiều yêu cầu: Quá nhiều yêu cầu đồng thời cho người dùng".

Lỗi 500, 502, 503, 504

Những lỗi này xảy ra khi có lỗi máy chủ không mong muốn trong quá trình xử lý yêu cầu. Nhiều vấn đề có thể gây ra các lỗi này, bao gồm cả thời gian của một yêu cầu trùng với một yêu cầu khác hoặc yêu cầu cho một hành động không được hỗ trợ, chẳng hạn như cố gắng cập nhật quyền cho một trang duy nhất trong Google Sites thay vì toàn bộ trang web.

Sau đây là danh sách các lỗi 5xx:

500 Lỗi trong chương trình phụ trợ
502 Cổng vào bị lỗi
503 Không có dịch vụ
504 Hết thời gian chờ của cổng nối

`backendError`

Lỗi này xảy ra khi có lỗi ngoài dự kiến trong quá trình xử lý yêu cầu. Mẫu JSON sau đây là một biểu thị của lỗi này:

{
  "error": {
  "errors": [
    {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
    }
  ],
  "code": 500,
  "message": "Backend Error"
  }
}

Để khắc phục lỗi này, hãy sử dụng thời gian đợi luỹ thừa để thử lại yêu cầu.

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 truy cập 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à thuật toán 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.

Quản lý 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.

Để biết thêm thông tin, hãy xem bài viết Xem và quản lý hạn mức.

Yêu cầu theo lô (Batch)

Các yêu cầu theo lô có thể cải thiện hiệu suất, nhưng 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 độ. Không 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 phần Yêu cầu hàng loạt.