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ô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 API Merchant 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 về
thông tin chi tiết lỗi, cung cấp thông tin có thể đọc được bằng máy để ứng dụng của bạn có thể xử lý các tình huống lỗi cụ thể theo phương thức 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 là phản hồi lỗi cũng bao gồm một mảng details. Để xử lý lỗi theo phương thức 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 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. 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. - 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ả các lỗi, 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 thông tin.
- Các trường động khác: Các khoá khác cung cấp thông tin, 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).
- REASON: Giá trị nhận dạng cụ thể, ổn định cho lỗi chính xác (ví dụ:
Phản hồi lỗi mẫu
JSON sau đây minh hoạ cấu trúc của lỗi Merchant API trong đó tên tài nguyên bị định dạng sai.
{
"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 có thể dựa vào và những 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.- Khoá
details.metadata: 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) là ổn định.
- Khoá
Trường không ổn định:
message: Thông báo lỗi mà con người có thể đọc được là không ổn định. Thông báo 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ườngmessagefield, 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 thông tin.- Giá trị
details.metadata: Mặc dù khoá là ổn định, nhưng giá trị cho các khoá thông tin có thể thay đổi. Ví dụ: nếu khoáHELP_CENTER_LINKđược cung cấp, thì URL cụ thể mà khoá đó trỏ đến có thể được cập nhật thành 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ủadetails.metadata.REASONlà ổ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 quy trình tích hợp của bạn xử lý lỗi một cách suôn sẻ.
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. Khô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 tính ổ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 không hoạt động tạm thời 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 đợi với mỗi lần không thành công 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 nhóm hạn mức cụ thể. Giảm tỷ lệ yêu cầu của bạn.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ếuinternal_errorvẫn tiếp diễn sau nhiều lần thử lại với thời gian đợi luỹ thừa, hãy xem bài viết Cách liên hệ với nhóm hỗ trợ Merchant API để được hỗ trợ.
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 thông tin sau trong yêu cầu của bạn:
- Phản hồi 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 trong đó phương thức được gọi và lỗi được nhận