API Marketing

Giới hạn tốc độ của API Marketing

API Marketing có logic giới hạn tốc độ riêng và không thuộc bất kỳ giới hạn tốc độ nào của API Đồ thị. Vì vậy, nếu bạn thực hiện lệnh gọi API Marketing, lệnh gọi đó sẽ không được tính vào giới hạn tốc độ của API Đồ thị.

Tính năng ảnh hưởng đến định mức giới hạn tốc độ của API Marketing là Quyền truy cập tiêu chuẩn để quản lý quảng cáo. Khi thêm sản phẩm API Marketing vào Bảng điều khiển ứng dụng, bạn sẽ mặc định có Quyền truy cập tiêu chuẩn của Quyền truy cập tiêu chuẩn để quản lý quảng cáo. Nhờ vậy, bạn sẽ có quyền truy cập phát triển vào API Marketing. Nếu bạn cần nâng cấp để tăng định mức giới hạn tốc độ, hãy nâng cấp lên Quyền truy cập nâng cao của Quyền truy cập tiêu chuẩn để quản lý quảng cáo trong quy trình Xét duyệt ứng dụng.

Định mức

Quyền truy cập API MarketingQuyền truy cập tiêu chuẩn để quản lý quảng cáoDung lượng

Quyền truy cập phát triển

Quyền truy cập tiêu chuẩn

Định mức giới hạn tốc độ cơ bản

Quyền truy cập tiêu chuẩn

Quyền truy cập nâng cao

Định mức giới hạn tốc độ cao hơn

Hầu hết yêu cầu API Marketing và yêu cầu API Trang đều tuân theo Giới hạn tốc độ cho trường hợp sử dụng của doanh nghiệp (BUC), đồng thời phụ thuộc vào các điểm cuối mà bạn đang truy vấn. Bạn có thể tìm ra giới hạn này bằng cách kiểm tra xem yêu cầu HTTP có chứa tiêu đề X-Business-Use-Case hay không. Hãy xem thêm chi tiết trong phần Giới hạn tốc độ cho trường hợp sử dụng của doanh nghiệp.

Giới hạn tốc độ API ở cấp độ tài khoản quảng cáo

  • Giới hạn tốc độ ở cấp độ tài khoản quảng cáo.
  • Giới hạn tốc độ diễn ra trong thời gian thực vào một khoảng thời gian nhất định.
  • Mỗi lệnh gọi API Marketing được chỉ định một điểm số. Điểm số của bạn là tổng điểm của các lệnh gọi API mà bạn gửi.
  • Chúng tôi thực thi điểm số tối đa. Nói chung, lệnh gọi API đọc tương đương 1 điểm và lệnh gọi API ghi tương đương 3 điểm. Khi bạn đạt điểm số tối đa, chúng tôi sẽ trả về lỗi giới hạn tốc độ.
    • Nếu ứng dụng của bạn ở cấp phát triển đối với API Marketing:
      • Điểm số tối đa của bạn là 60.
      • Tỷ lệ suy giảm là 300 giây.
      • Bạn sẽ bị chặn truy cập trong 300 giây khi đạt điểm số tối đa.
    • Nếu ứng dụng của bạn ở cấp Tiêu chuẩn đối với API Marketing:
      • Điểm số tối đa của bạn là 9000.
      • Tỷ lệ suy giảm là 300 giây.
      • Bạn sẽ bị chặn truy cập trong 60 giây khi đạt điểm số tối đa.

Mã lỗi liên quan:17, Error subcode: 2446079, Message: User request limit reached. 613, Error subcode: 1487742, Message: There have been too many calls from this ad-account. Please wait a bit and try again.

Giới hạn tốc độ QPS ở cấp độ tài khoản quảng cáo

Để tránh tình trạng lưu lượng truy cập tăng đột biến làm quá tải hệ thống, chúng tôi giới hạn tốc độ trong thời gian thực đối với các điểm cuối có chức năng biến đổi (thao tác tạo hoặc chỉnh sửa chiến dịch, nhóm quảng cáo và quảng cáo) của API Marketing.

  • Giới hạn tốc độ ở cấp độ tài khoản quảng cáo, theo ứng dụng.
  • Giới hạn: 100 yêu cầu mỗi giây (QPS) mỗi cách kết hợp ứng dụng và tài khoản.
  • Áp dụng cho: Thao tác tạo và chỉnh sửa chiến dịch, nhóm quảng cáo và quảng cáo.
  • Giới hạn này hoạt động trong thời gian thực và nhằm phát hiện những lần lưu lượng truy cập tăng đột biến trong thời gian ngắn mà mức giới hạn tốc độ tiêu chuẩn có thể không phát hiện ra.

Các điểm cuối sau đây sẽ bị ảnh hưởng:

Trong trường hợp bạn vượt qua giới hạn này, hãy dàn trải yêu cầu đồng đều hơn theo thời gian thay vì gửi yêu cầu với số lượng tăng đột biến.

Mã lỗi liên quan:613, Error subcode: 5044001, Message: Your ad account {ad_account_id} has exceeded the maximum allowed rate of mutation requests. To resolve this, reduce the frequency of your create, update operations on campaigns, ad sets, and ads.

Khi gặp phải lỗi này, hãy giới hạn tốc độ yêu cầu để duy trì tốc độ dưới 100 QPS cho mỗi tài khoản quảng cáo.

Giới hạn tốc độ nền tảng Thông tin chi tiết về quảng cáo

  • Giới hạn tốc độ ở cấp độ ứng dụng.
  • Giới hạn tốc độ được xác định dựa trên dung lượng của cơ sở hạ tầng phụ trợ và dịch vụ hỗ trợ.
  • Khi ứng dụng của bạn bị giới hạn tốc độ, mọi lệnh gọi API Thông tin chi tiết về quảng cáo cho ứng dụng đó đều bị giới hạn.
  • Chúng tôi thực thi giới hạn tốc độ ở cấp độ ứng dụng.

Mã lỗi liên quan:4, Error subcode: 1504022 or 1504039, Message: There have been too many calls from this app. Wait a bit and try again.

Khi gặp lỗi này, hãy giảm số lượng lệnh gọi của bạn.

Giới hạn ở cấp độ ứng dụng

  • Giới hạn tốc độ ở cấp độ ứng dụng.
  • Giới hạn tốc độ được xác định dựa trên tổng số người dùng của ứng dụng.
  • Khi ứng dụng của bạn bị giới hạn tốc độ, mọi lệnh gọi cho ứng dụng đó đều bị giới hạn.
  • Chúng tôi thực thi giới hạn tốc độ ở cấp độ ứng dụng.

Mã lỗi liên quan:4, Message: Application request limit reached

Khi gặp lỗi này, hãy giảm số lượng lệnh gọi của bạn.

Giới hạn tốc độ cho trường hợp sử dụng của doanh nghiệp ở cấp độ tài khoản quảng cáo

Chúng tôi sẽ tính định mức giới hạn tốc độ này dựa trên cấp truy cập vào API Marketing và ứng dụng của bạn.

  • Giới hạn tốc độ ở cấp độ tài khoản quảng cáo và định mức được tính dựa trên cấp truy cập vào API quảng cáo ứng dụng của bạn.
  • ads_management - Đối với mỗi tài khoản quảng cáo trong khoảng thời gian một giờ: (100.000 nếu ứng dụng của bạn ở cấp truy cập Tiêu chuẩn vào API Marketing hoặc 300 nếu ứng dụng của bạn ở cấp truy cập Phát triển) + 40 * Số lượng quảng cáo đang hoạt động.
  • custom_audience - Đối với mỗi tài khoản quảng cáo trong khoảng thời gian một giờ: Không quá 700.000. Không dưới 190.000 nếu ứng dụng của bạn ở cấp truy cập Tiêu chuẩn vào API Marketing hoặc 5.000 nếu ứng dụng của bạn ở cấp truy cập Phát triển + 40 * Số lượng đối tượng tùy chỉnh đang hoạt động.
  • ads_insights - Đối với mỗi tài khoản quảng cáo trong khoảng thời gian một giờ: (190.000 nếu ứng dụng của bạn ở cấp truy cập Tiêu chuẩn vào API Quảng cáo hoặc 600 nếu ứng dụng của bạn ở cấp truy cập Phát triển) + 400 * Số lượng quảng cáo đang hoạt động - 0,001 * Số lỗi người dùng.
  • Quản lý danh mục - Đối với mỗi tài khoản quảng cáo trong khoảng thời gian một giờ: 20.000 + 20.000 * log2(số người dùng khác nhau).
  • Loạt danh mục - Đối với mỗi tài khoản quảng cáo trong khoảng thời gian một giờ: 200 + 200 * log2(số người dùng khác nhau).
  • Giới hạn tốc độ API Marketing của bạn cũng có thể được xác định dựa trên Tổng thời gian CPU và Tổng thời gian thực đã qua trong tài khoản quảng cáo của bạn. Bạn sẽ có định mức cao hơn nếu ứng dụng của bạn có Quyền truy cập tiêu chuẩn vào API Marketing, hãy kiểm tra tiêu đề HTTP [X-Business-Use-Case](/docs/graph-api/overview/rate-limiting/#headers-2) và Giới hạn tốc độ cho trường hợp sử dụng của doanh nghiệp để biết thêm chi tiết.

Mã lỗi liên quan:80000, 80003, 80004, 80014, Message: There have been too many calls from this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.

Xác minh điểm cuối API và tiêu đề HTTP X-Business-Use-Case để xác nhận loại giới hạn tốc độ. Hãy xem thêm chi tiết trong phần Giới hạn tốc độ cho trường hợp sử dụng của doanh nghiệp. Khi gặp lỗi này, hãy giảm số lần thay đổi đối với tài khoản quảng cáo.

Giới hạn tốc độ chi tiêu quảng cáo ở cấp độ tài khoản quảng cáo

Bạn chỉ được thay đổi giới hạn chi tiêu cho tài khoản của mình 10 lần mỗi ngày để đảm bảo hiệu quả phân phối quảng cáo.

  • Số lần thay đổi đối với các trường liên quan đến chi tiêu cho tài khoản quảng cáo như spend_cap, spend_cap_action bị giới hạn

Mã lỗi liên quan:17, Error subcode: 1885172, Message: You can only change your account spending limit 10 times per day. Please wait to make more changes.

Giới hạn ở cấp độ nhóm quảng cáo

Số lần thay đổi đối với các trường daily_budget và lifetime_budget cho nhóm quảng cáo bị giới hạn. Đối với mỗi nhóm quảng cáo, bạn chỉ được phép thay đổi ngân sách 4 lần mỗi giờ. Nếu vượt quá giới hạn này, bạn sẽ bị chặn thay đổi ngân sách cho nhóm quảng cáo đó trong một giờ.

Mã lỗi liên quan:613, Error subcode: 1487632, Message: You can only change your ad set budget 4 times per hour. Please wait to make more changes.

Khi gặp lỗi này, hãy giảm số lần thay đổi đối với nhóm quảng cáo.

Giới hạn ở cấp độ quảng cáo

Một tài khoản quảng cáo nhất định bị giới hạn số lần tạo quảng cáo dựa trên giới hạn chi tiêu hàng ngày.

Mã lỗi liên quan:613, Error subcode: 1487225, Message: User request limit reached.

Xác minh mã lỗi phụ (1487225) và điểm cuối API để xác nhận loại giới hạn tốc độ. Khi gặp lỗi này, hãy giảm số lần thay đổi. Để tăng giới hạn của mình, bạn cũng có thể tăng giới hạn chi tiêu hàng ngày.

Giới hạn tốc độ chống lạm dụng

Khi hệ thống của chúng tôi phát hiện thấy rằng một số tài khoản quảng cáo tạo ra lượng lớn lưu lượng truy cập bất thường, để giữ độ ổn định cho hệ thống và đảm bảo trải nghiệm của những người dùng khác, chúng tôi sẽ tạm thời giảm định mức Giới hạn tốc độ API của các tài khoản bất thường. Vui lòng thử liên hệ với bộ phận hỗ trợ của Meta để được trợ giúp.

Mã lỗi liên quan:613, Error subcode: null, Message: (#613) Calls to this api have exceeded the rate limit.

Khác với Giới hạn tốc độ API ở cấp độ tài khoản quảng cáo, lỗi này không có mã lỗi phụ. Khi gặp lỗi này, hãy điều tra xem có hành động nào kích hoạt quá nhiều yêu cầu API hay không và liên hệ với bộ phận hỗ trợ của Meta để được trợ giúp.

Xử lý lỗi giới hạn tốc độ

Đánh giá ban đầu

Kiểm tra cấp truy cập vào API Marketing:

Theo mặc định, các ứng dụng có development_access vào API Marketing. Để biết mình ở cấp truy cập nào, bạn có thể mở bảng điều khiển Xét duyệt ứng dụng. Nếu có Quyền truy cập tiêu chuẩn vào tính năng Quyền truy cập tiêu chuẩn để quản lý quảng cáo, bạn đang ở cấp truy cập phát triển vào API Marketing. Nếu có Quyền truy cập nâng cao vào tính năng Quyền truy cập tiêu chuẩn để quản lý quảng cáo, bạn đang ở cấp truy cập tiêu chuẩn vào API Marketing. Bạn cũng có thể kiểm tra tiêu đề HTTP và tìm ads_api_access_tier trong tiêu đề X-Ad-Account-Usage, X-Business-Use-Case hoặc X-FB-Ads-Insights-Throttle.

Nếu bạn liên tục gặp lỗi giới hạn tốc độ, hãy xem xét nâng cấp lên standard_access của Quyền truy cập tiêu chuẩn để quản lý quảng cáo. Để có cấp truy cập tiêu chuẩn và định mức giới hạn tốc độ cao hơn, bạn có thể đăng ký Quyền truy cập nâng cao vào tính năng Quyền truy cập tiêu chuẩn để quản lý quảng cáo trong bảng điều khiển Xét duyệt ứng dụng.

  • Kiểm tra mã lỗi: Xác định các mã lỗi cụ thể liên quan đến giới hạn tốc độ trong phản hồi API.
  • Kiểm tra tiêu đề HTTP:
    • X-Ad-Account-Usage chứa acc_id_util_pct, reset_time_duration và ads_api_access_tier.
    • X-Business-Use-Case chứa thông tin về call_count, total_cputime, total_time và estimated_time_to_regain_access, v.v. cho điểm cuối Trường hợp sử dụng của doanh nghiệp.
    • X-FB-Ads-Insights-Throttle chứa app_id_util_pct, acc_id_util_pct và ads_api_access_tier đối với điểm cuối API Thông tin chi tiết về quảng cáo.
  • Kiểm tra Bảng điều khiển ứng dụng: Chúng tôi cung cấp các bảng điều khiển trong Bảng điều khiển ứng dụng để giúp nhà phát triển nắm được thông tin chi tiết chuyên sâu về hệ thống giới hạn tốc độ, từ đó có thể chẩn đoán và ngăn chặn các vấn đề về giới hạn tốc độ.

Xác định nguyên nhân

  • Giới hạn tốc độ: Tìm hiểu giới hạn tốc độ API Marketing của Meta cho các điểm cuối khác nhau đang được sử dụng và xác minh xem số lượng yêu cầu API có nằm trong giới hạn cho phép của ứng dụng hay không.
  • Giới hạn đột biến: Kiểm tra xem giới hạn đột biến có gây ra vấn đề trong thời gian sử dụng cao điểm hay không. Thông thường, lưu lượng truy cập đột biến sẽ gây ra Giới hạn tốc độ API ở cấp độ tài khoản quảng cáo (Mã lỗi liên quan:17, 613).
  • Thao tác sai: Điều tra xem có thao tác sai nào kích hoạt quá nhiều yêu cầu API hay không.

Các bước giảm thiểu

  • Ngăn chặn lưu lượng truy cập đột biến: Phân bổ đều yêu cầu API để tránh bị giới hạn tốc độ do lượng truy cập lớn trong một khoảng thời gian ngắn.
  • Tối ưu hóa yêu cầu: Kết hợp nhiều yêu cầu nhỏ hơn thành yêu cầu hàng loạt, có thể là loạt ID hoặc yêu cầu không đồng bộ để giảm thiểu tổng số lượng yêu cầu API.
  • Chiến lược lùi bước: Triển khai chiến lược lùi bước theo cấp số nhân khi nhận được lỗi giới hạn tốc độ, tăng dần thời gian giữa các lần thử lại. Bạn cũng có thể kiểm tra tiêu đề HTTP để ước tính thời gian đặt lại.

Bí quyết khác để giảm số lệnh gọi

  • Hiểu rõ nhu cầu và giảm bớt các lệnh gọi này nếu không cần thiết.
  • Đối với các điểm cuối hỗ trợ yêu cầu không đồng bộ như API Thông tin chi tiết về quảng cáo, hãy sử dụng Yêu cầu không đồng bộ để truy vấn lượng dữ liệu lớn.
  • Bạn cũng có thể thử chuyển một danh sách ID nếu cần truy vấn nhiều đối tượng quảng cáo cùng loại.
  • Đối với API Thông tin chi tiết, hãy sử dụng Thông số cấp độ hoặc lọc để giảm số lượng lệnh gọi.