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 sàn. 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`	Gói chưa mở nền tảng này	Nâng gói
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 danh sách endpoint
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	Phải là `tiktok-ads`
404	`token_not_found`	Kết nối chưa cấp quyền, hoặc token đã bị thu hồi phía TikTok	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`	TikTok đang giới hạn ở cấp ứng dụng	Chờ theo `Retry-After` (tới 300 giây)
502	`upstream_unreachable`	Không gọi được TikTok	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 TikTok¶

HTTP 200 nhưng code trong body khác 0. Đây là response nguyên văn của TikTok, Logidata không đụng vào:

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

Luôn kiểm tra body.code, đừng chỉ nhìn HTTP status

TikTok 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.

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.

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¶

import httpx, time

def call(path, params, key, account_id, tries=3):
    for attempt in range(tries):
        r = httpx.get(f"https://api.logidata.vn/v1/tiktok-ads{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()
        if body.get("code") != 0:                      # lỗi nghiệp vụ của TikTok
            raise RuntimeError(f"TikTok {body['code']}: {body.get('message')}")
        return body["data"]