Các lỗi thường gặp
Khi thực hiện các yêu cầu API, việc đảm bảo cấu trúc và định dạng chính xác là yếu tố then chốt để giao tiếp suôn sẻ với máy chủ của TikTok Shop. Chủ đề này đề cập đến các lỗi xuyên miền (cross-domain) liên quan đến request query, header và body format. Những lỗi cơ bản này xảy ra trước khi xử lý logic nghiệp vụ và phải được khắc phục thì yêu cầu mới được xử lý thành công.
📌 Lưu ý: Giá trị 0 trong mã phản hồi (response code) cho biết yêu cầu đã được xử lý thành công.
Lỗi chung
| Code | Error message | Chi tiết và hướng dẫn |
|---|---|---|
| 36009002 | Too many requests. You've made too many requests in a short period of time. | Vui lòng đợi và thử lại. Tham khảo Rate limits để biết chi tiết. |
| 36009007 | Request timeout. The request to the endpoint timed out. | Vui lòng thử lại, hoặc cân nhắc chia nhỏ thành các yêu cầu nhỏ hơn. |
| 36009009 | Invalid path. The specified path does not match any available endpoint. | Tham khảo tài liệu API để biết chi tiết. |
| 36009010 | Invalid method. The HTTP method used is not supported by this endpoint. | Tham khảo tài liệu API để biết chi tiết. |
| 36009021 | Invalid file size. The uploaded file size exceeds the maximum limit. | Tham khảo tài liệu API để biết chi tiết. |
| 36009022 | Invalid request format. The request body format must be application/json for structured data or multipart/form-data for binary files. | Tham khảo tài liệu API để biết chi tiết. |
| 36009023 | Invalid request format. The value of the content-type header must be multipart/form-data. | Tham khảo tài liệu API để biết chi tiết. |
Lỗi cấp quyền (Authorization)
| Code | Error message | Chi tiết và hướng dẫn |
|---|---|---|
| 101000 | Invalid query or header. The category_asset_cipher query parameter or x-tts-access-token header is invalid. | Đối với category_asset_cipher, hãy đảm bảo bạn lấy đúng giá trị từ endpoint Get Authorized Category Assets. |
Đối với x-tts-access-token, các nguyên nhân có thể bao gồm:
- Token có
user_typekhông hợp lệ cho endpoint này. - Token không được liên kết với shop nào, hoặc shop được liên kết không khớp với tham số query
shop_cipherđã cung cấp.
Tham khảo hướng dẫn cấp quyền để biết chi tiết. | | 105005 | Access denied. The app is not authorized to access the endpoint because the access scopes granted for the app or the access token do not contain the required access scope for the endpoint. | Các bước kiểm tra được đề xuất:
- Kiểm tra các scope đã được cấp cho app tại Partner Center > App & Service > Manage API. Nếu thiếu scope cần thiết, hãy đăng ký hoặc bật scope đó trong Partner Center.
- Kiểm tra các scope đã được cấp cho token trong trường
granted_scopescủa phản hồi Get Access Token. Nếu thiếu scope cần thiết, hãy yêu cầu người dùng cấp quyền lại cho scope đó, sau đó tạo token mới tương ứng. | | 36009033 | Access denied. Your IP address is not in the IP allow list configured for this app. | Thêm địa chỉ IP của bạn tại Partner Center > App & Service. |
Lỗi xác thực (Authentication)
| Code | Error message | Chi tiết và hướng dẫn |
|---|---|---|
| 105002 | Expired credentials. The access_token or x-tts-access-token header has expired. | Làm mới token của bạn bằng cách sử dụng endpoint Get Refresh Token. |
| 106001 | Invalid credentials. The sign query parameter is invalid. | Đảm bảo bạn tạo chữ ký hợp lệ bằng cách tham khảo hướng dẫn ký yêu cầu của bạn. |
| 36009004 | Missing credentials. The request does not include a required signature in the query. | Tạo chữ ký bằng cách tham khảo hướng dẫn ký yêu cầu của bạn. |
| 36009004 | Invalid credentials. The access_token header is invalid. | Vui lòng truyền vào access_token mà bạn đã lấy từ endpoint Get Access Token. |
| 36009004 | Invalid credentials. The x-tts-access-token header is invalid. | Vui lòng truyền vào access_token mà bạn đã lấy từ endpoint Get Access Token. |
| 36009004 | Invalid credentials. Invalid app_key query parameter. | Các nguyên nhân có thể bao gồm định dạng key không hợp lệ, không tìm thấy app, app bị vô hiệu hóa hoặc đã bị xóa, hoặc có lỗi khi truy xuất thông tin cấp quyền cần thiết. Đảm bảo bạn lấy đúng giá trị từ trang App details trong Partner Center. |
| 36009004 | Invalid timestamp. The value of the timestamp query parameter must not be lesser than 0. | Dấu thời gian (timestamp) phải nằm trong khoảng từ 5 phút trước đến 30 giây sau thời điểm hiện tại. |
| 36009004 | Invalid timestamp. The value of the timestamp query parameter must not be earlier than 5 minutes before the current time. | Dấu thời gian (timestamp) phải nằm trong khoảng từ 5 phút trước đến 30 giây sau thời điểm hiện tại. |
| 36009004 | Invalid timestamp. The value of the timestamp query parameter must not exceed the current time by more than 30 seconds. | Dấu thời gian (timestamp) phải nằm trong khoảng từ 5 phút trước đến 30 giây sau thời điểm hiện tại. |
Lỗi tham số (Parameter)
| Code | Error message | Chi tiết và hướng dẫn |
|---|---|---|
| 106013 | Missing identifier. The shop_cipher query parameter is required to identify the target shop. | Lấy giá trị này từ endpoint Get Authorized Shops. |
| 36009004 | Unexpected identifier. The shop_cipher query parameter is not required for this request. | Xóa nó đi và thử lại. Tham khảo tài liệu API để biết chi tiết về định danh (identifier) cần thiết. |
| 36009004 | Unexpected identifier. The category_asset_cipher query parameter is not required for this request. | Xóa nó đi và thử lại. Tham khảo tài liệu API để biết chi tiết về định danh (identifier) cần thiết. |
| 36009004 | Invalid identifier. The shop_id query parameter is invalid. | Lấy đúng giá trị từ endpoint Get Authorized Shops. |
| 36009004 | Invalid API version. The version query parameter is invalid. | Tham khảo tài liệu API để tìm hiểu các phiên bản API hợp lệ. |
| 36004004 | Invalid auth code | auth_code đã được sử dụng, đã hết hạn, hoặc không hợp lệ. |