Tìm hiểu về lỗi API

Hướng dẫn này giải thích cách Google Ads API xử lý và thông báo lỗi. Việc hiểu rõ cấu trúc và ý nghĩa của lỗi API là rất quan trọng để xây dựng các ứng dụng mạnh mẽ có thể xử lý các vấn đề một cách linh hoạt, từ dữ liệu đầu vào không hợp lệ đến tình trạng dịch vụ tạm thời không hoạt động.

Google Ads API tuân theo mô hình lỗi API chuẩn của Google, dựa trên mã trạng thái gRPC. Mỗi phản hồi của API dẫn đến lỗi đều bao gồm một đối tượng Status chứa:

  • Mã lỗi dạng số.
  • Thông báo lỗi.
  • Thông tin chi tiết khác về lỗi (không bắt buộc).

Mã lỗi chuẩn

Google Ads API sử dụng một tập hợp mã lỗi chuẩn do gRPC và HTTP xác định. Các mã này cung cấp thông tin tổng quan về loại lỗi. Bạn phải luôn kiểm tra mã số này trước tiên để hiểu bản chất cơ bản của vấn đề.

Bảng sau đây tóm tắt các mã phổ biến nhất mà bạn có thể gặp phải khi sử dụng API Google Ads:

mã gRPC Mã HTTP Tên enum Mô tả Hướng dẫn
0 200 OK Không có lỗi; cho biết thành công. Không áp dụng
1 499 CANCELLED Thao tác đã bị huỷ, thường là do ứng dụng. Thường có nghĩa là ứng dụng khách đã ngừng chờ. Kiểm tra thời gian chờ phía máy khách.
2 500 UNKNOWN Đã xảy ra lỗi không xác định. Thông báo lỗi hoặc thông tin chi tiết có thể cung cấp thêm thông tin. Xem như lỗi phía máy chủ. Thường có thể thử lại bằng cách đợi một khoảng thời gian.
3 400 INVALID_ARGUMENT Ứng dụng đã chỉ định một đối số không hợp lệ. Điều này cho biết một vấn đề khiến API không thể xử lý yêu cầu, chẳng hạn như tên tài nguyên không đúng định dạng hoặc giá trị không hợp lệ. Lỗi ứng dụng: Hãy xem lại các tham số yêu cầu và đảm bảo các tham số đó đáp ứng yêu cầu của API. Thông tin chi tiết về lỗi thường cung cấp thông tin về đối số không hợp lệ và lý do không hợp lệ. Hãy sử dụng thông tin này để khắc phục yêu cầu. Đừng thử lại nếu chưa khắc phục yêu cầu.
4 504 DEADLINE_EXCEEDED Đã hết hạn trước khi thao tác có thể hoàn tất. Lỗi phía máy chủ: Thường là tạm thời. Hãy cân nhắc thử lại bằng thuật toán thời gian đợi luỹ thừa.
5 404 NOT_FOUND Không tìm thấy một số thực thể được yêu cầu, chẳng hạn như chiến dịch hoặc nhóm quảng cáo. Lỗi ứng dụng: Xác minh sự tồn tại và mã nhận dạng của tài nguyên mà bạn đang cố gắng truy cập. Đừng thử lại nếu chưa chỉnh sửa.
6 409 ALREADY_EXISTS Thực thể mà ứng dụng khách cố gắng tạo đã tồn tại. Lỗi ứng dụng: Tránh tạo tài nguyên trùng lặp. Kiểm tra xem tài nguyên có tồn tại hay không trước khi cố gắng tạo tài nguyên.
7 403 PERMISSION_DENIED Phương thức gọi không có quyền thực thi thao tác đã chỉ định. Lỗi ứng dụng: Kiểm tra thông tin xác thực, quyền uỷ quyền và vai trò của người dùng đối với tài khoản Google Ads. Đừng thử lại nếu chưa giải quyết vấn đề về quyền.
8 429 RESOURCE_EXHAUSTED Tài nguyên đã hết (ví dụ: bạn đã vượt quá hạn mức) hoặc hệ thống bị quá tải. Lỗi ứng dụng/máy chủ: Thường cần phải chờ. Triển khai thuật toán thời gian đợi luỹ thừa và có thể giảm tỷ lệ yêu cầu. Xem Giới hạn và hạn mức API.
9 400 FAILED_PRECONDITION Thao tác bị từ chối vì hệ thống không ở trạng thái cần thiết để thực thi thao tác. Ví dụ: thiếu một trường bắt buộc. Lỗi ứng dụng: Yêu cầu hợp lệ nhưng trạng thái không chính xác. Hãy xem thông tin chi tiết về lỗi để tìm hiểu về lỗi điều kiện tiên quyết. Đừng thử lại nếu chưa sửa trạng thái.
10 409 ABORTED Thao tác đã bị huỷ, thường là do vấn đề đồng thời như xung đột giao dịch. Lỗi phía máy chủ: Thường có thể thử lại một cách an toàn sau một khoảng thời gian ngắn.
11 400 OUT_OF_RANGE Thao tác đã được thực hiện ngoài phạm vi hợp lệ. Lỗi ứng dụng: Sửa dải ô hoặc chỉ mục.
12 501 UNIMPLEMENTED Thao tác này không được triển khai hoặc không được API hỗ trợ. Lỗi ứng dụng: Kiểm tra phiên bản API và các tính năng có sẵn. Đừng thử lại.
13 500 INTERNAL Đã xảy ra lỗi nội bộ. Đây là lỗi chung cho các vấn đề phía máy chủ. Lỗi phía máy chủ: Thường có thể thử lại bằng thuật toán thời gian đợi luỹ thừa. Nếu vấn đề vẫn tiếp diễn, hãy báo cáo vấn đề.
14 503 UNAVAILABLE Dịch vụ này tạm thời không hoạt động. Đây có thể là một tình trạng tạm thời. Lỗi phía máy chủ: Bạn nên thử lại bằng thuật toán thời gian đợi luỹ thừa.
15 500 DATA_LOSS Mất hoặc hỏng dữ liệu không thể khôi phục. Lỗi phía máy chủ: Hiếm. Cho biết một vấn đề nghiêm trọng. Đừng thử lại. Nếu vấn đề vẫn tiếp diễn, hãy báo cáo vấn đề.
16 401 UNAUTHENTICATED Yêu cầu không có thông tin xác thực hợp lệ. Lỗi ứng dụng: Xác minh mã xác thực và thông tin đăng nhập của bạn. Đừng thử lại nếu chưa khắc phục được lỗi xác thực.

Để biết thêm thông tin chi tiết về các mã này, hãy tham khảo Hướng dẫn thiết kế API – Mã lỗi.

Tìm hiểu thông tin chi tiết về lỗi

Ngoài mã cấp cao nhất, Google Ads API còn cung cấp thông tin lỗi cụ thể hơn trong trường details của đối tượng Status. Trường này thường chứa một proto GoogleAdsFailure, trong đó có danh sách các đối tượng GoogleAdsError riêng lẻ.

Mỗi đối tượng GoogleAdsFailure chứa:

  • errors: Danh sách các đối tượng GoogleAdsError, mỗi đối tượng trình bày chi tiết một lỗi cụ thể đã xảy ra.
  • request_id: Mã nhận dạng duy nhất cho yêu cầu, hữu ích cho mục đích gỡ lỗi và hỗ trợ.

Mỗi đối tượng GoogleAdsError cung cấp:

Ví dụ về thông tin chi tiết về lỗi

Khi bạn nhận được lỗi, thư viện ứng dụng sẽ cho phép bạn truy cập vào các thông tin chi tiết này. Ví dụ: INVALID_ARGUMENT (Mã 3) có thể có GoogleAdsFailure thông tin chi tiết như sau:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v26.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ],
      "requestId": "AbCdEfGhIjKlMnOpQrStUv"
    }
  ]
}

Trong ví dụ này, mặc dù có INVALID_ARGUMENT cấp cao nhất, nhưng thông tin chi tiết về GoogleAdsFailure cho bạn biết rằng các trường name và description đã gây ra vấn đề và lý do (lần lượt là REQUIRED và TOO_SHORT).

Thông tin chi tiết về lỗi tìm vị trí

Cách bạn truy cập vào thông tin chi tiết về lỗi phụ thuộc vào việc bạn đang sử dụng lệnh gọi API tiêu chuẩn, lỗi một phần hay truyền trực tuyến.

Lệnh gọi API chuẩn và lệnh gọi API truyền trực tuyến

Khi một lệnh gọi API không thành công mà không sử dụng lỗi một phần, bao gồm cả lệnh gọi truyền trực tuyến, đối tượng GoogleAdsFailure sẽ được trả về dưới dạng một phần của siêu dữ liệu theo sau trong tiêu đề phản hồi gRPC. Nếu bạn đang sử dụng REST cho các lệnh gọi chuẩn, thì GoogleAdsFailure sẽ được trả về trong phản hồi HTTP. Thư viện ứng dụng thường hiển thị thông tin này dưới dạng một ngoại lệ có thuộc tính GoogleAdsFailure.

Không thực hiện được một phần

Nếu bạn đang sử dụng tính năng lỗi một phần, thì lỗi cho các thao tác không thành công sẽ được trả về trong trường partial_failure_error của phản hồi, chứ không phải trong tiêu đề phản hồi. Trong trường hợp này, GoogleAdsFailure được nhúng trong đối tượng google.rpc.Status trong phản hồi.

Công việc theo lô

Đối với xử lý hàng loạt, bạn có thể tìm thấy lỗi cho từng thao tác bằng cách gọi BatchJobService.ListBatchJobResults sau khi công việc hoàn tất. Mỗi kết quả thao tác sẽ bao gồm một trường status chứa thông tin chi tiết về lỗi nếu thao tác không thành công.

Mã yêu cầu

request-id là một chuỗi duy nhất giúp xác định yêu cầu API của bạn và là thông tin cần thiết để khắc phục sự cố.

Bạn có thể tìm thấy request-id ở nhiều nơi:

  • GoogleAdsFailure: Nếu lệnh gọi API không thành công và trả về GoogleAdsFailure, thì lệnh gọi đó sẽ chứa request_id.
  • Siêu dữ liệu theo sau: Đối với cả yêu cầu thành công và không thành công, request-id đều có trong siêu dữ liệu theo sau của phản hồi gRPC.
  • Tiêu đề phản hồi: Đối với cả yêu cầu thành công và không thành công, request-id cũng có trong tiêu đề phản hồi gRPC và phản hồi HTTP, ngoại trừ các yêu cầu truyền trực tuyến thành công.
  • SearchGoogleAdsStreamResponse: Đối với các yêu cầu truyền trực tuyến, mỗi thông báo SearchGoogleAdsStreamResponse đều chứa một trường request_id.

Khi ghi nhật ký lỗi hoặc liên hệ với nhóm hỗ trợ, hãy nhớ cung cấp request-id để giúp chẩn đoán vấn đề.

Các phương pháp hay nhất để xử lý lỗi

Để xây dựng ứng dụng có khả năng thích ứng, hãy triển khai các phương pháp hay nhất sau đây:

  1. Kiểm tra thông tin chi tiết về lỗi: Luôn phân tích cú pháp trường details của đối tượng Status, cụ thể là tìm GoogleAdsFailure. error_code, message và location chi tiết trong GoogleAdsError cung cấp thông tin hữu ích nhất để gỡ lỗi và phản hồi của người dùng.

  2. Phân biệt lỗi ứng dụng với lỗi phía máy chủ:

    • Lỗi máy khách: Các mã như INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Những lỗi này yêu cầu bạn phải thay đổi yêu cầu hoặc trạng thái/thông tin xác thực của ứng dụng. Đừng thử gửi lại yêu cầu nếu chưa giải quyết vấn đề.
    • Lỗi phía máy chủ: Các mã như UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Những lỗi này cho thấy dịch vụ API đang gặp sự cố tạm thời.

  3. Triển khai chiến lược thử lại:

    • Trường hợp nên thử lại: Chỉ thử lại đối với các lỗi tạm thời của máy chủ, chẳng hạn như UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN và ABORTED.
    • Thuật toán thời gian đợi luỹ thừa: Sử dụng thuật toán thời gian đợi luỹ thừa để chờ khoảng thời gian tăng dần giữa các lần thử lại. Điều này giúp tránh làm quá tải một dịch vụ vốn đã bị quá tải. Ví dụ: đợi 1 giây, sau đó là 2 giây, rồi 4 giây, tiếp tục cho đến khi đạt số lần thử lại tối đa hoặc tổng thời gian chờ.
    • Biên độ: Thêm một lượng "biên độ" ngẫu nhiên nhỏ vào độ trễ của thời gian đợi để ngăn chặn vấn đề "thundering herd" (bầy đàn sấm sét) khi nhiều ứng dụng khách thử lại cùng một lúc.

  4. Ghi nhật ký đầy đủ: Ghi nhật ký toàn bộ phản hồi lỗi, bao gồm tất cả thông tin chi tiết, đặc biệt là mã yêu cầu. Thông tin này rất cần thiết cho việc gỡ lỗi và báo cáo vấn đề cho Nhóm hỗ trợ Google nếu cần.

  5. Cung cấp ý kiến phản hồi của người dùng: Dựa trên các mã và thông báo GoogleAdsError cụ thể, hãy cung cấp ý kiến phản hồi rõ ràng và hữu ích cho người dùng ứng dụng. Ví dụ: thay vì chỉ nói "Đã xảy ra lỗi", bạn có thể nói "Cần có tên chiến dịch" hoặc "Không tìm thấy mã nhóm quảng cáo được cung cấp".

Bằng cách làm theo các nguyên tắc này, bạn có thể chẩn đoán và xử lý hiệu quả các lỗi do Google Ads API trả về, nhờ đó tạo ra các ứng dụng ổn định và thân thiện hơn với người dùng.

Trước
Các loại lỗi
Tiếp
Lỗi thường gặp