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ô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ủa bạn phải phát hiện và xử lý tất cả các lỗi có thể xảy ra 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`	Không thể thực hiện yêu cầu do lỗi ứng dụng trong yêu cầu.
`401 - Unauthorized`	Yêu cầu chứa thông tin đăng nhập không hợp lệ.
`403 - Forbidden`	Yêu cầu đã được nhận và hiể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 trang đượ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 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:

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ệ.

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ệ. 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. 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.
Đã vượt quá giới hạn 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ề số lượng dự án.

Để 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 xuất hiện 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. 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."
  }
}

Để 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 rằng 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 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 bạn đạ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 "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ử lại các yêu cầu không thành công hoặc bằng cách chia nhỏ 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 cho mỗi người dù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. 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 hạn mức này được á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, ứng dụng web hay MSA SMTP. Nếu vượt quá các giới hạn này, 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ư)" sẽ được trả về cùng với thời gian thử lại. Nếu vượt quá giới hạn hằng ngày, bạn có thể gặp phải những 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. 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 dùng chung cho tất cả ứng dụng Gmail API của một người dùng.

Các 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, hệ thống 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" kèm theo thời gian để thử lại. Việc vượt quá giới hạn hằng ngày có thể dẫn đến những 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 đề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. 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 "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 tạo bằng Google Sites.

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

500 Lỗi trong chương trình phụ trợ
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

backendError

Lỗi này xảy ra khi có lỗi không mong muố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 phần Xem và quản lý hạn mức.

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

Bạn nên sử dụng các yêu cầu 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 xử lý hàng loạt các yêu cầu, hãy tham khảo phần Yêu cầu hàng loạt.