Trang này được dịch bởi Cloud Translation API.

Xử lý phản hồi lỗi

Hướng dẫn này giải thích cách xử lý các lỗi do Merchant API trả về. Việc hiểu rõ cấu trúc và tính ổn định của phản hồi lỗi là rất quan trọng để xây dựng các quy trình tích hợp mạnh mẽ có thể tự động khắc phục lỗi hoặc cung cấp thông tin phản hồi có ý nghĩa cho người dùng.

Tổng quan

Khi một yêu cầu Merchant API không thành công, API sẽ trả về mã trạng thái HTTP tiêu chuẩn (4xx hoặc 5xx) và một nội dung phản hồi JSON chứa thông tin chi tiết về lỗi. Merchant API tuân theo tiêu chuẩn AIP-193 để biết thông tin chi tiết về lỗi, cung cấp thông tin mà máy có thể đọc được, cho phép ứng dụng của bạn xử lý các trường hợp lỗi cụ thể theo phương thức lập trình.

Cấu trúc phản hồi lỗi

Phản hồi lỗi là một đối tượng JSON chứa các trường tiêu chuẩn như code, message và status. Điều quan trọng là nó cũng bao gồm một mảng details. Để xử lý lỗi theo cách lập trình, bạn nên tìm một đối tượng trong details, trong đó @type là type.googleapis.com/google.rpc.ErrorInfo.

Đối tượng ErrorInfo này cung cấp dữ liệu có cấu trúc, ổn định về lỗi:

domain: Nhóm logic của lỗi, thường là merchantapi.googleapis.com.
metadata: Bản đồ các giá trị động liên quan đến lỗi. Trong đó có:
- REASON: Giá trị nhận dạng cụ thể và ổn định cho lỗi chính xác (ví dụ: INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). Trường này luôn xuất hiện. Sử dụng trường này để xử lý lỗi chi tiết trong logic ứng dụng của bạn.
- HELP_CENTER_LINK: Cung cấp thêm bối cảnh và hướng dẫn để khắc phục vấn đề. Không phải lỗi nào cũng có trường này, nhưng chúng tôi dự định sẽ mở rộng phạm vi của trường này theo thời gian đối với những lỗi cần thêm bối cảnh.
- Các trường động khác: Các khoá khác cung cấp bối cảnh, chẳng hạn như tên của trường không hợp lệ (FIELD_LOCATION) hoặc giá trị gây ra lỗi (FIELD_VALUE).

Phản hồi lỗi mẫu

JSON sau đây minh hoạ cấu trúc của một lỗi Merchant API trong đó tên tài nguyên bị lỗi.

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

Dưới đây là ví dụ về lỗi xác thực:

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

Tính ổn định của các trường lỗi

Khi viết logic xử lý lỗi, bạn cần biết những trường nào an toàn để dựa vào và những trường nào có thể thay đổi.

Các trường ổn định:
details.metadata.REASON: Giá trị nhận dạng lỗi cụ thể. Bạn nên dựa vào trường này cho logic luồng điều khiển của ứng dụng.
- details.metadata khoá: Các khoá trong bản đồ siêu dữ liệu (ví dụ: FIELD_LOCATION, ACCOUNT_IDS) ổn định.
- code: Mã trạng thái HTTP cấp cao (ví dụ: 400, 401, 503) ổn định.
Các trường không ổn định:
- message: Thông báo lỗi mà con người có thể đọc được không ổn định. Chế độ này chỉ dành cho việc gỡ lỗi của nhà phát triển. Không viết mã phân tích cú pháp hoặc dựa vào nội dung văn bản của trường message, vì nội dung này có thể thay đổi mà không có thông báo để cải thiện độ rõ ràng hoặc thêm ngữ cảnh.
- Giá trị details.metadata: Mặc dù khoá ổn định, nhưng giá trị của khoá thông tin có thể thay đổi. Ví dụ: nếu bạn cung cấp một khoá HELP_CENTER_LINK, thì URL cụ thể mà khoá đó trỏ đến có thể được cập nhật thành một trang tài liệu mới hơn mà không cần thông báo trước. Tuy nhiên, như đã đề cập trước đó, giá trị của details.metadata.REASON là ổn định.

Các phương pháp hay nhất

Hãy làm theo các phương pháp hay nhất này để đảm bảo quá trình tích hợp của bạn xử lý lỗi một cách hiệu quả.

Sử dụng `details.metadata.REASON` cho logic

Luôn sử dụng REASON cụ thể bên trong bản đồ metadata để xác định nguyên nhân gây ra lỗi. Đừng chỉ dựa vào mã trạng thái HTTP, vì nhiều lỗi có thể dùng chung một mã trạng thái.

Không phân tích cú pháp thông báo lỗi

Như đã lưu ý trong phần độ ổn định, trường message là dành cho người dùng. Nếu bạn cần thông tin động (chẳng hạn như trường nào không hợp lệ), hãy trích xuất thông tin đó từ bản đồ metadata bằng các khoá ổn định như FIELD_LOCATION, VARIABLE_NAME.

Triển khai thuật toán thời gian đợi luỹ thừa

Đối với những lỗi cho biết tình trạng tạm thời không có sẵn hoặc giới hạn tốc độ, hãy triển khai chiến lược thời gian đợi luỹ thừa. Điều này có nghĩa là bạn phải đợi một khoảng thời gian ngắn trước khi thử lại và tăng thời gian chờ sau mỗi lần thất bại tiếp theo.

quota/request_rate_too_high: Lỗi này cho biết bạn đã vượt quá hạn mức phút cho một nhóm hạn mức cụ thể. Giảm tần suất yêu cầu.
internal_error: Đây thường là các lỗi tạm thời. Thử lại với thời gian đợi luỹ thừa. Lưu ý: Nếu internal_error vẫn tiếp diễn sau nhiều lần thử lại với độ trễ, hãy xem phần Cách liên hệ với nhóm hỗ trợ Merchant API.

Cách liên hệ với nhóm hỗ trợ Merchant API

Nếu bạn cần liên hệ với nhóm hỗ trợ Merchant API về một lỗi cụ thể, hãy cung cấp những thông tin sau trong yêu cầu của bạn:

Thông báo lỗi chính xác nhận được
Tên phương thức API
Tải trọng của yêu cầu
Dấu thời gian hoặc phạm vi thời gian mà phương thức được gọi và nhận được lỗi