Mã lỗi¶

Có hai loại lỗi, hình dạng khác hẳn nhau. Phân biệt đúng loại là bước đầu để xử lý đúng.

Lỗi của Logidata¶

Sinh ra trước khi request tới nền tảng. Giống nhau ở mọi nền tảng — code xử lý lỗi bạn viết một lần dùng được cho cả TikTok Ads, Shopee lẫn Google Ads. Luôn có hình dạng:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Đã dùng hết hạn mức tháng",
    "request_id": "6f1c2f0e-…"
  }
}

request_id cũng nằm ở header X-Request-Id. Gửi kèm giá trị này khi báo lỗi cho Logidata — nó dẫn thẳng tới log của đúng request đó.

HTTP	`code`	Nghĩa là gì	Làm gì
401	`missing_api_key`	Thiếu header `X-API-Key`	Thêm header
401	`invalid_api_key`	Key sai hoặc đã bị thu hồi	Kiểm tra lại key; nếu vừa "Đổi key" thì cập nhật giá trị mới
403	`subscription_expired`	Gói đã hết hạn	Gia hạn. Kết nối và key được giữ nguyên
403	`subscription_suspended`	Tài khoản đang tạm ngưng	Liên hệ Logidata
403	`provider_not_in_plan`	API key chưa có nền tảng này trong danh sách (mọi gói đã mở toàn bộ nền tảng — lỗi này chỉ còn gặp với key cũ chưa đồng bộ)	Báo Logidata để đồng bộ lại key
403	`account_not_allowed`	`X-Account-Id` không thuộc key này	Xem lại giá trị ở trang Kết nối
403	`path_not_allowed`	Endpoint ngoài allowlist (mặc định chỉ đọc)	Xem nền tảng được hỗ trợ
403	`ip_not_allowed`	IP gọi không nằm trong allowlist của key	Báo Logidata dải IP mới
400	`missing_account_id`	Key có nhiều kết nối, phải chỉ rõ	Thêm header `X-Account-Id`
404	`unknown_provider`	Sai tên nền tảng trong URL	Đối chiếu tên nền tảng trong bảng nền tảng
404	`token_not_found`	Kết nối chưa cấp quyền, hoặc token đã bị thu hồi phía nền tảng	Vào portal bấm Cấp lại quyền
429	`rate_limited`	Vượt tần suất của key	Chờ theo `Retry-After` rồi thử lại
429	`quota_exceeded`	Hết hạn mức tháng	Chờ sang tháng, hoặc nâng gói
429	`upstream_rate_limited`	Sàn đang giới hạn ở cấp ứng dụng	Chờ theo `Retry-After` (tới 300 giây)
429	`youtube_quota_exhausted`	Quota YouTube Data API dùng chung trong ngày đã tới ngưỡng ngắt	Chờ sang ngày mới (nửa đêm giờ Thái Bình Dương). Được hoàn lại hạn mức tháng
401	`token_revoked`	Kênh YouTube / tài khoản Google đã thu hồi quyền hoặc đổi mật khẩu	Vào portal bấm Cấp lại quyền
403	`customer_id_mismatch`	`customer_id` trong đường dẫn Google Ads không khớp kết nối	Dùng đúng `customer_id` của `X-Account-Id` đang gọi
502	`upstream_unreachable`	Không gọi được nền tảng	Thử lại. Không bị tính vào hạn mức

429 và 502 nên retry, 4xx còn lại thì không

rate_limited, upstream_rate_limited, upstream_unreachable là lỗi tạm thời — retry có ích. Các mã 401/403/404 là lỗi cấu hình; retry chỉ đốt hạn mức.

Lỗi của nền tảng¶

Đây là response nguyên văn của nền tảng, Logidata không đụng vào — nên hình dạng khác nhau theo từng nền tảng. Điểm chung: phần lớn nền tảng trả HTTP 200 kèm mã lỗi nghiệp vụ trong body.

Nền tảng	Dấu hiệu thành công	Tra mã lỗi ở
`tiktok-ads`, `tiktok-shop`	`code == 0` trong body	TikTok Business API
`shopee`, `shopee-ads`	trường `error` rỗng trong body	Shopee Open Platform
`google-ads`, `youtube`, `google-search-console`, `google-sheets`	HTTP 2xx, không có object `error`	Google Ads · YouTube Data

TikTok¶

HTTP 200 nhưng code trong body khác 0:

{ "code": 40002, "message": "Invalid advertiser_id", "data": {} }

Luôn kiểm tra mã lỗi trong body, đừng chỉ nhìn HTTP status

Các nền tảng trả 200 cho phần lớn lỗi nghiệp vụ. Code chỉ kiểm response.ok sẽ lặng lẽ nuốt mất chúng — và vì mỗi nền tảng một quy ước, hàm kiểm tra phải viết riêng cho từng nền tảng. (Lỗi của Logidata thì ngược lại: một hình dạng duy nhất cho mọi nền tảng.)

Mã thường gặp:

`code`	Nghĩa
`0`	Thành công
`40001`	Thiếu tham số bắt buộc
`40002`	Tham số sai định dạng hoặc sai giá trị
`40100`	Vượt giới hạn tần suất cấp ứng dụng
`40105`	Token không hợp lệ — vào portal bấm Cấp lại quyền
`40700`, `40900`	Không có quyền trên advertiser đó

Tra đầy đủ ở tài liệu TikTok Business API.

Shopee¶

Response luôn có error và message. error rỗng nghĩa là thành công:

{ "error": "error_param", "message": "Invalid time range", "response": {} }

Lỗi hay gặp: khoảng thời gian vượt giới hạn cho phép của endpoint, và token hết hạn (error_auth) — trường hợp thứ hai Logidata xử lý hộ bằng cơ chế làm mới token nền, bạn chỉ gặp nó nếu shop đã thu hồi quyền, khi đó vào portal bấm Cấp lại quyền.

40100 được xử lý đặc biệt

Khi TikTok trả 40100, Logidata mở circuit breaker 5 phút cho toàn bộ nền tảng và trả cho bạn 429 upstream_rate_limited kèm Retry-After: 300. Đây là cố ý: gọi tiếp trong lúc bị phạt chỉ kéo dài thời gian phạt.

Mẫu xử lý lỗi¶

Phần xử lý lỗi Logidata (khối if/raise đầu tiên) dùng chung cho mọi nền tảng; chỉ bước kiểm tra body ở cuối là riêng theo nền tảng.

import httpx, time

def call(provider, path, params, key, account_id, tries=3):
    for attempt in range(tries):
        r = httpx.get(f"https://api.logidata.vn/v1/{provider}{path}",
                      params=params, timeout=60,
                      headers={"X-API-Key": key, "X-Account-Id": account_id})

        if r.status_code in (429, 502):
            if attempt == tries - 1:
                r.raise_for_status()
            time.sleep(int(r.headers.get("Retry-After", 2 ** attempt)))
            continue

        if r.status_code >= 400:
            err = r.json()["error"]
            # Lỗi cấu hình: retry vô ích, hỏng ở đâu thì dừng ở đó
            raise RuntimeError(f"{err['code']}: {err['message']} "
                               f"(request_id={err['request_id']})")

        body = r.json()
        # Quy ước kiểm tra lỗi nghiệp vụ khác nhau theo nền tảng
        if provider.startswith("tiktok") and body.get("code") != 0:
            raise RuntimeError(f"{provider} {body['code']}: {body.get('message')}")
        if provider.startswith("shopee") and body.get("error"):
            raise RuntimeError(f"{provider} {body['error']}: {body.get('message')}")
        return body