Hướng dẫn này giải thích cách API Google Ads xử lý và truyền đạt lỗi. Việc hiểu rõ cấu trúc và ý nghĩa của các lỗi API là điều 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 hiệu quả, từ đầu vào không hợp lệ cho đến tình trạng dịch vụ tạm thời không hoạt động.
API Google Ads tuân theo mô hình lỗi API tiêu chuẩn của Google, dựa trên mã trạng thái gRPC. Mỗi phản hồi API dẫn đến lỗi đều có một đối tượng Status chứa:
- Mã lỗi bằng số.
- Một thông báo lỗi.
- Thông tin chi tiết bổ sung không bắt buộc về lỗi.
Mã lỗi chuẩn
API Google Ads sử dụng một bộ mã lỗi chuẩn do gRPC và HTTP xác định. Các mã này cho biết loại lỗi ở cấp độ cao. Trước tiên, bạn phải luôn kiểm tra mã số này để hiểu rõ 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 khách. | 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ể chứa thêm thông tin. | Coi đây là lỗi máy chủ. Thường có thể thử lại với độ trễ tăng dần. |
| 3 | 400 | INVALID_ARGUMENT |
Ứng dụng khách chỉ định đối số không hợp lệ. Điều này cho biết có vấn đề khiến API không xử lý được yêu cầu, chẳng hạn như tên tài nguyên bị lỗi hoặc giá trị không hợp lệ. | Lỗi phía máy khách: Xem lại các tham số yêu cầu và đảm bảo chúng đáp ứng các 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à cách sử dụng những thông tin chi tiết này để sửa 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 thời hạn trước khi thao tác có thể hoàn tất. | Lỗi máy chủ: Thường là lỗi tạm thời. Hãy cân nhắc việ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 khách: 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 mà không chỉnh sửa. |
| 6 | 409 | ALREADY_EXISTS |
Thực thể mà ứng dụng khách tìm cách 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 |
Người gọi không có quyền thực thi thao tác đã chỉ định. | Lỗi ứng dụng khách: Kiểm tra quy trình xác thực, 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 các vấn đề về quyền. |
| 8 | 429 | RESOURCE_EXHAUSTED |
Tài nguyên đã cạn kiệt (ví dụ: bạn đã vượt quá hạn mức) hoặc hệ thống bị quá tải. | Lỗi máy khách/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ốc độ yêu cầu. Xem Hạn mức và giới hạn 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 hiện 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 state không chính xác. Xem thông tin chi tiết về lỗi để hiểu rõ lý do không đáp ứng được điều kiện tiên quyết. Đừng thử lại khi chưa sửa trạng thái. |
| 10 | 409 | ABORTED |
Thao tác bị huỷ bỏ, thường là do vấn đề về tính đồng thời, chẳng hạn như xung đột giao dịch. | Lỗi máy chủ: Thường an toàn khi thử lại với thời gian chờ 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 |
API không triển khai hoặc không hỗ trợ thao tác này. | Lỗi phía máy khách: Kiểm tra phiên bản API và các tính năng hiện có. Đừng thử lại. |
| 13 | 500 | INTERNAL |
Đã xảy ra lỗi nội bộ. Đây là danh mục chung cho các vấn đề phía máy chủ. | Lỗi 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 hiện không dùng được. Đây rất có thể là một tình trạng tạm thời. | Lỗi máy chủ: Rất 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ư hỏng dữ liệu và không phục hồi được. | Lỗi máy chủ: Hiếm gặp. Cho biết có 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 phía máy khách: Xác minh mã thông báo 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 giao thức GoogleAdsFailure, trong đó có một danh sách các đối tượng GoogleAdsError riêng lẻ.
Mỗi đối tượng GoogleAdsFailure đều chứa:
errors: Danh sách các đối tượngGoogleAdsError, mỗi đối tượng trình bày chi tiết một lỗi cụ thể đã xảy ra.request_id: Một 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 đều cung cấp:
errorCode: Mã lỗi cụ thể của Google Ads API chi tiết hơn, chẳng hạn nhưAuthenticationError.NOT_ADS_USER.message: Nội dung mô tả cụ thể về lỗi mà con người có thể đọc được.trigger: Giá trị gây ra lỗi (nếu có).location: Mô tả vị trí xảy ra lỗi trong yêu cầu, bao gồm cả đường dẫn trường.details: Thông tin chi tiết bổ sung về lỗi, chẳng hạn như lý do lỗi chưa được công bố.
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 những thông tin chi tiết này. Ví dụ: INVALID_ARGUMENT (Mã 3) có thể có thông tin chi tiết GoogleAdsFailure như sau:
{
"code": 3,
"message": "The request was invalid.",
"details": [
{
"@type": "type.googleapis.com/google.ads.googleads.v17.errors.GoogleAdsFailure",
"errors": [
{
"errorCode": {
"fieldError": "REQUIRED"
},
"message": "The required field was not present.",
"location": {
"fieldPathElements": [
{ "fieldName": "operations" },
{ "fieldName": "create" },
{ "fieldName": "name" }
]
}
},
{
"errorCode": {
"stringLengthError": "TOO_SHORT"
},
"message": "The provided string is too short.",
"trigger": {
"stringValue": ""
},
"location": {
"fieldPathElements": [
{ "fieldName": "operations" },
{ "fieldName": "create" },
{ "fieldName": "description" }
]
}
}
]
}
]
}
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 biết các trường name và description đã gây ra vấn đề và lý do (tương ứng là REQUIRED và TOO_SHORT).
Tìm thông tin chi tiết về lỗi
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 tiêu 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ị điều này dưới dạng một trường hợp 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 lỗi một phần, thì các lỗi cho những 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 một đố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 của từng thao tác bằng cách truy xuất kết quả của công việc hàng loạt 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à rất cần thiết cho việc khắc phục sự cố.
Bạn có thể tìm thấy request-id ở nhiều nơi:
GoogleAdsFailure: Nếu một lệnh gọi API không thành công vàGoogleAdsFailuređược trả về, thì lệnh gọi đó sẽ chứa mộtrequest_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-idcũng có trong tiêu đề phản hồi gRPC và HTTP, ngoại trừ các yêu cầu phát trực tuyến thành công. SearchGoogleAdsStreamResponse: Đối với các yêu cầu phát trực tuyến, mỗi thông báoSearchGoogleAdsStreamResponseđều chứa một trườngrequest_id.
Khi ghi nhật ký lỗi hoặc liên hệ với nhóm hỗ trợ, hãy nhớ thêm request-id để giúp chẩn đoán vấn đề.
Các phương pháp hay nhất để xử lý lỗi
Để tạo các ứng dụng có khả năng phục hồi, hãy triển khai các phương pháp hay nhất sau đây:
Kiểm tra thông tin chi tiết về lỗi: Luôn phân tích cú pháp trường
detailscủa đối tượngStatus, đặc biệt là tìmGoogleAdsFailure.errorCode,messagevàlocationchi tiết trongGoogleAdsErrorcung cấp thông tin hữu ích nhất để gỡ lỗi và thu thập ý kiến phản hồi của người dùng.Phân biệt lỗi máy khách với lỗi máy chủ:
- Lỗi phía 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 thay đổi yêu cầu hoặc trạng thái/thông tin đăng nhập của ứng dụng. Đừng thử lại yêu cầu mà không giải quyết vấn đề. - Lỗi 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 vấn đề tạm thời.
- Lỗi phía máy khách: Các mã như
Triển khai chiến lược thử lại:
- Thời điểm thử lại: Chỉ thử lại đối với các lỗi máy chủ tạm thời như
UNAVAILABLE,DEADLINE_EXCEEDED,INTERNAL,UNKNOWNvà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 gây quá tải cho một dịch vụ vốn đã chịu nhiều áp lực. Ví dụ: đợi 1 giây, sau đó đợi 2 giây, rồi đợi 4 giây, tiếp tục cho đến 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 nhỏ "biên độ" ngẫu nhiên vào độ trễ đợi luỹ tiến để ngăn chặn vấn đề "đàn gia súc" khi nhiều ứng dụng đồng thời thử lại.
- Thời điểm thử lại: Chỉ thử lại đối với các lỗi máy chủ tạm thời như
Ghi nhật ký kỹ lưỡng: 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ợ của Google nếu cần.
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 cụ thể
GoogleAdsError, 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 của bạn. Ví dụ: thay vì chỉ nói "Đã xảy ra lỗi", bạn có thể nói "Bạn phải nhập 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 tuân thủ 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ề, dẫn đến các ứng dụng ổn định và thân thiện với người dùng hơn.