Phản hồi lỗi

Phản hồi về lỗi chuẩn

Nếu yêu cầu API Báo cáo chính 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ề 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ị không hợp lệ.	Đừng thử lại mà không khắc phục vấn đề. Bạn cần cung cấp giá trị hợp lệ cho tham số được chỉ định trong phản hồi lỗi.
400	`badRequest`	Cho biết truy vấn không hợp lệ. Ví dụ: thiếu mã nhận dạng gốc hoặc tổ hợp phương diện hay chỉ số được yêu cầu không hợp lệ.	Đừng thử lại mà không khắc phục vấn đề. Bạn cần thay đổi truy vấn API để truy vấn đó hoạt động.
401	`invalidCredentials`	Cho biết 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 vấn đề. 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 vấn đề. Bạn cần có đủ quyền để thực hiện thao tác trên thực thể đã chỉ định.
403	`dailyLimitExceeded`	Cho biết rằng người dùng đã vượt quá hạn mức hằng ngày (mỗi dự án hoặc mỗi lượt xem (hồ sơ)).	Đừng thử lại mà không khắc phục vấn đề. Bạn đã sử dụng hết hạn mức hằng ngày. Xem bài viết Giới hạn và hạn mức API.
403	`userRateLimitExceeded`	Cho biết rằng bạn đã vượt quá giới hạn Truy vấn/100 giây/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 tài khoản.	Thử lại bằng cách sử dụng 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 mỗi 100 giây của dự án.	Thử lại bằng cách sử dụng 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 lượt xem (hồ sơ) trong API báo cáo chính.	Thử lại bằng cách sử dụ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 tiến hành để chế độ xem (hồ sơ) này hoàn tất.
500	`internalServerError`	Đã xảy ra lỗi máy chủ nội bộ không mong muốn.	Không thử truy vấn này nhiều lần.
503	`backendError`	Máy chủ trả về một lỗi.	Không thử truy vấn này nhiều lần.

Xử lý các phản hồi 500 hoặc 503

Lỗi 500 hoặc 503 có thể xảy ra trong quá trình tải quá mức hoặc đối với các yêu cầu lớn hơn và 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 khoảng thời gian ngắn hơn. Bạn cũng nên cân nhắc việc triển khai thuật toán thời gian đợi luỹ thừa. Tần suất xảy ra các 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 được liên kết với chế độ xem đó. 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 một 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 báo cáo chính được thiết kế với kỳ vọng rằng những khách hàng chọn thử lại các yêu cầu không thành công sẽ 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 còn 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 để có được phản hồi thành công và tối đa hoá thông lượng 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
Chờ 1 giây + random_number_milliseconds giây
Thử yêu cầu lại
Nhận phản hồi lỗi có mã lỗi có thể thử lại
Chờ 2 giây + random_number_milliseconds giây
Thử yêu cầu lại
Nhận phản hồi lỗi có mã lỗi có thể thử lại
Chờ 4 giây + random_number_milliseconds giây
Thử yêu cầu lại
Nhận phản hồi lỗi có mã lỗi có thể thử lại
Chờ 8 giây + random_number_milliseconds giây
Thử yêu cầu lại
Nhận phản hồi lỗi có mã lỗi có thể thử lại
Chờ 16 giây + random_number_milliseconds giây
Thử yêu cầu lại
Nếu bạn vẫn gặp lỗi, hãy dừng lại và ghi lại thông báo 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 1.000. Điều này là cần thiết để tránh một số lỗi khoá trong một số phương thức triển khai đồng thời. Bạn phải định nghĩa lại random_number_milliseconds sau mỗi lần chờ.

Lưu ý: thời gian chờ luôn là (2 ^ n) + random_number_milliseconds, trong đó n là số nguyên tăng đơn điệu ban đầu được xác định 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ỉ để ngăn ứng dụng thử lại vô hạn, và 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".

Mã Python sau đây là cách triển khai quy trình trên để khôi phục từ các lỗi xảy ra trong một 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."