Phản hồi lỗi chuẩn
Nếu yêu cầu API Quản lý thành công, API sẽ trả về mã trạng thái 200. Nếu xảy ra lỗi với một yêu cầu, API sẽ trả về mã trạng thái HTTP, trạng thái và lý do trong phản hồi dựa trên loại lỗi.
Ngoài ra, phần nội dung của phản hồi còn chứa nội dung mô tả chi tiết về nguyên nhân gây ra lỗi. Dưới đây là ví dụ về một phản hồi lỗi:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "invalidParameter",
"message": "Invalid value '-1' for max-results. Value must be within the range: [1, 1000]",
"locationType": "parameter",
"location": "max-results"
}
],
"code": 400,
"message": "Invalid value '-1' for max-results. Value must be within the range: [1, 1000]"
}
}
Bảng lỗi
| Mã | Lý do | Nội dung mô tả | Việc nên làm |
|---|---|---|---|
| 400 | invalidParameter |
Cho biết rằng tham số yêu cầu có giá trị không hợp lệ. Các trường locationType và location trong phản hồi lỗi cung cấp thông tin về giá trị nào không hợp lệ. |
Đừng thử lại mà không khắc phục sự cố. Bạn cần cung cấp một giá trị hợp lệ cho tham số được chỉ định trong phản hồi lỗi. |
| 400 | badRequest |
Cho biết rằng truy vấn không hợp lệ. Ví dụ: mã nhận dạng gốc bị thiếu hoặc tổ hợp phương diện hay chỉ số đã yêu cầu không hợp lệ. | Đừng thử lại mà không khắc phục sự cố. Bạn cần phải thay đổi truy vấn API để truy vấn đó có thể hoạt động. |
| 401 | invalidCredentials |
Cho biết rằng mã thông báo xác thực không hợp lệ hoặc đã hết hạn. | Đừng thử lại mà không khắc phục sự cố. Bạn cần nhận mã thông báo xác thực mới. |
| 403 | insufficientPermissions |
Cho biết rằng người dùng không có đủ quyền đối với thực thể được chỉ định trong truy vấn. | Đừng thử lại mà không khắc phục sự cố. Bạn cần có đủ quyền để thực hiện thao tác trên thực thể được chỉ định. |
| 403 | dailyLimitExceeded |
Cho biết rằng người dùng đã vượt quá hạn mức hằng ngày (cho mỗi dự án hoặc mỗi chế độ xem (hồ sơ)). | Đừng thử lại mà không khắc phục sự cố. Bạn đã dùng hết hạn mức hằng ngày. Xem Hạn mức và giới hạn API. |
| 403 | userRateLimitExceeded |
Cho biết rằng bạn đã vượt quá giới hạn Cụm từ tìm kiếm trên mỗi 100 giây cho mỗi người dùng. Giá trị mặc định được đặt trong Google API Console là 100 truy vấn/100 giây/người dùng. Bạn có thể tăng giới hạn này trong Google API Console lên tối đa 1.000. | Thử sử dụng lại phương pháp thời gian đợi luỹ thừa. Bạn cần giảm tốc độ gửi yêu cầu. |
| 403 | rateLimitExceeded |
Cho biết rằng bạn đã vượt quá giới hạn tốc độ truy vấn trên mỗi 100 giây của dự án. | Thử sử dụng lại phương pháp thời gian đợi luỹ thừa. Bạn cần giảm tốc độ gửi yêu cầu. |
| 403 | quotaExceeded |
Cho biết rằng đã đạt đến 10 yêu cầu đồng thời cho mỗi chế độ xem (hồ sơ) trong API báo cáo chính. | Thử lại bằng cách sử dụng tính năng thời gian đợi luỹ thừa. Bạn cần phải đợi ít nhất một yêu cầu đang xử lý để chế độ xem (hồ sơ) này hoàn tất. |
| 500 | internalServerError |
Đã xảy ra lỗi máy chủ nội bộ ngoài dự kiến. | Đừng thử lại truy vấn này nhiều lần. |
| 503 | backendError |
Máy chủ đã trả về một lỗi. | Đừng thử lại truy vấn này nhiều lần. |
Xử lý 500 hoặc 503 phản hồi
Lỗi 500 hoặc 503 có thể xảy ra trong quá trình tải nặng hoặc cho các yêu cầu lớn hơn, phức tạp hơn. Đối với các yêu cầu lớn hơn, hãy cân nhắc việc yêu cầu dữ liệu trong một khoảng thời gian ngắn hơn. Ngoài ra, hãy cân nhắc triển khai thời gian đợi luỹ thừa.
Tần suất xảy ra những lỗi này có thể phụ thuộc vào chế độ xem (hồ sơ) và số lượng dữ liệu báo cáo liên kết với chế độ xem đó; Một truy vấn gây ra lỗi 500 hoặc 503 cho một chế độ xem (hồ sơ) không nhất thiết gây ra lỗi cho cùng một truy vấn với chế độ xem (hồ sơ) khác.
Triển khai thuật toán thời gian đợi luỹ thừa
Thời gian đợi luỹ thừa là quá trình máy khách đị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. Đây là một chiến lược xử lý lỗi tiêu chuẩn cho các ứng dụng mạng. API Quản lý được thiết kế với kỳ vọng rằng các ứng dụng chọn thử lại các yêu cầu không thành công sẽ làm như vậy bằng cách sử dụng thuật toán thời gian đợi luỹ thừa. Ngoài việc là "bắt buộc", việc sử dụng thuật toán thời gian đợi luỹ thừa giúp tăng hiệu quả sử dụng băng thông, giảm số lượng yêu cầu cần thiết để nhận được phản hồi thành công và tối đa hoá công suất yêu cầu trong các môi trường đồng thời.
Quy trình triển khai thuật toán thời gian đợi luỹ thừa đơn giản như sau.
- Gửi yêu cầu đến API
- Nhận phản hồi lỗi có mã lỗi có thể thử lại
- Đợi 1 giây +
random_number_millisecondsgiây - Thử gửi lại yêu cầu
- Nhận phản hồi lỗi có mã lỗi có thể thử lại
- Đợi 2 giây +
random_number_millisecondsgiây - Thử gửi lại yêu cầu
- Nhận phản hồi lỗi có mã lỗi có thể thử lại
- Đợi 4 giây +
random_number_millisecondsgiây - Thử gửi lại yêu cầu
- Nhận phản hồi lỗi có mã lỗi có thể thử lại
- Đợi 8 giây +
random_number_millisecondsgiây - Thử gửi lại yêu cầu
- Nhận phản hồi lỗi có mã lỗi có thể thử lại
- Chờ 16 giây +
random_number_millisecondsgiây - Thử gửi lại yêu cầu
- Nếu bạn vẫn gặp lỗi, hãy dừng lại và ghi lại lỗi đó.
Trong quy trình trên, random_number_milliseconds là một số mili giây ngẫu nhiên nhỏ hơn hoặc bằng 1000. Việc này là cần thiết để tránh một số lỗi khoá nhất định trong một số quá trình triển khai đồng thời.
random_number_milliseconds phải được xác định lại sau mỗi lần chờ.
Lưu ý: thời gian chờ luôn là (2 ^ n) + random_number_milliseconds, trong đó n là một số nguyên tăng đơn điệu được xác định ban đầu là 0. n được tăng thêm 1 cho mỗi lần lặp (mỗi yêu cầu).
Thuật toán sẽ được đặt để kết thúc khi n là 5. Mức trần này chỉ được áp dụng để ngăn ứng dụng thử lại vô hạn, dẫn đến độ trễ tổng cộng khoảng 32 giây trước khi một yêu cầu bị coi là "lỗi không thể khôi phục".
Đoạn mã Python sau đây là cách triển khai quy trình ở trên để khôi phục sau các lỗi xảy ra trong phương thức có tên là makeRequest.
import random
import time
from apiclient.errors import HttpError
def makeRequestWithExponentialBackoff(analytics):
"""Wrapper to request Google Analytics data with exponential backoff.
The makeRequest method accepts the analytics service object, makes API
requests and returns the response. If any error occurs, the makeRequest
method is retried using exponential backoff.
Args:
analytics: The analytics service object
Returns:
The API response from the makeRequest method.
"""
for n in range(0, 5):
try:
return makeRequest(analytics)
except HttpError, error:
if error.resp.reason in ['userRateLimitExceeded', 'quotaExceeded',
'internalServerError', 'backendError']:
time.sleep((2 ** n) + random.random())
else:
break
print "There has been an error, the request never succeeded."