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

Hướng dẫn này giải thích cách xử lý lỗi do Merchant API trả về. Việc hiểu rõ cấu trúc và độ ổ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ôi phục sau lỗi hoặc cung cấp ý kiến 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ột 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 về thông tin chi tiết về lỗi, cung cấp thông tin có thể đọc được bằng máy, 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. Quan trọng nhất là lớp này cũng bao gồm một mảng details. Để xử lý lỗi theo phương thức 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 ổn định, có cấu trúc 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. bao gồm:
    • REASON: Giá trị nhận dạng cụ thể, ổ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 thông tin và hướng dẫn để khắc phục vấn đề. Trường này không xuất hiện cho tất cả lỗi, nhưng chúng tôi dự định sẽ mở rộng phạm vi áp dụng theo thời gian cho những lỗi có thể 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 lỗi Merchant API khi tên tài nguyên không đúng định dạng.

{
  "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 trường nào an toàn để dựa vào và trường nào có thể thay đổi.

  • 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) là ổn định.
    • code: Mã trạng thái HTTP cấp cao (ví dụ: 400, 401, 503) ổn định.

  • 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. Tệp này chỉ dành cho nhà phát triển gỡ lỗi. Đừ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ần thông báo để cải thiện độ rõ ràng hoặc thêm ngữ cảnh.
    • details.metadata giá trị: Mặc dù khoá ổn định, nhưng giá trị cho khoá thông tin có thể thay đổi. Ví dụ: nếu bạn cung cấp 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 sau đây để đảm bảo quá trình tích hợp của bạn xử lý lỗi một cách linh hoạt.

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ể có cùng 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 các lỗi cho biết tình trạng tạm thời không hoạt động 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 cần đợ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 không thành công.

  • quota/request_rate_too_high: Lỗi này cho biết bạn đã vượt quá hạn mức phút cho nhóm hạn mức cụ thể. Hãy giảm tỷ lệ yêu cầu.
  • internal_error: Những lỗi này thường chỉ là tạm thời. Thử lại với thời gian đợi luỹ thừa.

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

Nếu bạn cần liên hệ với bộ phận hỗ trợ của 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:

  1. Nội dung phản hồi lỗi chính xác mà bạn nhận được
  2. Tên phương thức API
  3. Tải trọng của yêu cầu
  4. 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
Trước
Track usage metrics
Tiếp
Error messages