API Lỗi
Lỗi
Body lỗi mà mọi endpoint trả về, cách status code ứng với loại lỗi, và các mã lỗi client cần xử lý.
Nhà phát triển Tham chiếu 2 phút đọc
Mọi response lỗi có chung một dạng body:
{
"error": {
"code": "invalid_request",
"message": "request does not match the API description",
"fields": { "phone_token": "required" },
"trace_id": "4bf92f3577b34da6..."
}
}codecố định, dạngsnake_case. App map nó sang câu tiếng Việt của mình.messagelà tiếng Anh, dành cho developer, không hiện cho người dùng.fieldscó khi request sai hình dạng, mỗi trường sai một mục, key là đường dẫn JSON của trường. Giá trị là luật bị vi phạm, ví dụrequired,minLength,additionalProperties.detailschứa giá trị mà client cần dùng, ví dụretry_aftertính bằng giây.trace_idtrùng với headerTrace-Idcủa response. Khi báo lỗi thì gửi kèm nó, từ đó tìm ra request trong log và trace.
Status code
| Status | Ý nghĩa | Mã thường gặp |
|---|---|---|
| 400 | Request không khớp spec | invalid_request, malformed_json |
| 401 | Không có thông tin đăng nhập hợp lệ | unauthenticated, invalid_token, invalid_refresh_token, session_revoked, session_expired, invalid_phone_token |
| 403 | Tài khoản bị khóa | account_suspended |
| 404 | Không có tài nguyên này với người gọi | listing_not_found, deal_not_found, … |
| 409 | Lần ghi đụng với lần ghi khác | try_again |
| 413 | Body quá 1 MB | body_too_large |
| 422 | Đúng hình dạng nhưng vi phạm một luật | mỗi luật một mã, ví dụ invalid_phone |
| 428 | Người gọi phải làm một việc trước | reauth_required |
| 429 | Bị giới hạn tần suất | xem details.retry_after |
| 500 | Lỗi ngoài dự kiến | internal |
| 503 | Một dịch vụ mà request cần đang không chạy | unavailable |
Tài nguyên mà người gọi không được xem cũng trả 404, giống như tài nguyên không tồn tại. Ví dụ phiên của tài khoản khác là 404.
try_again dùng chung cho mọi module: lần ghi thua một lần ghi khác vào cùng bản ghi, gửi lại là an toàn. Mỗi operation trong spec liệt kê các mã nó có thể trả, nên xem operation trước khi xử lý một mã.
Nguyên nhân thật của lỗi 500 chỉ nằm trong log server, không bao giờ nằm trong body.
Mã lỗi theo ca sử dụng
Luồng ngoại lệ nào kết thúc bằng một mã lỗi thì ghi mã đó trong registry. Bảng dưới sinh từ các mã đó; mã không có ở đây là mã dùng chung cho mọi module hoặc chưa được truy vết tới ca sử dụng nào.
| Mã lỗi | Luồng | Liên quan |
|---|---|---|
account_suspended | ||
address_not_found | | |
blocked | ||
carrier_address_unknown | | |
carrier_not_linked | | |
carrier_unavailable | | |
cod_limit_reached | ||
deal_changed | | |
invalid_amount | ||
invalid_listing | ||
invalid_shipment | | |
invalid_upload | | |
listing_cap_reached | ||
listing_not_found | ||
listing_state_conflict | | |
listing_unavailable | | |
move_not_allowed | | |
own_listing | | |
phone_required | ||
price_changed | ||
read_limit_reached | | |
shipment_not_found | ||
unsupported_source | |