마케팅 API 사용 제한

마케팅 API에는 자체 사용 제한 로직이 있으며 모든 그래프 API 사용 제한에서 제외됩니다. 따라서 마케팅 API를 호출하는 경우 그래프 API 제한에 반영하여 계산되지 않습니다.

마케팅 API 사용 제한 할당량에 영향을 미치는 기능은 광고 관리 표준 액세스입니다. 마케팅 API 제품을 앱 대시보드에 추가하면 기본적으로 광고 관리 표준 액세스의 표준 액세스 권한을 얻게 됩니다. 그러면 마케팅 API에 대한 개발 액세스 권한을 얻을 수 있습니다. 더 높은 사용 제한 할당량으로 업그레이드해야 할 경우 앱 검수에서 광고 관리 표준 액세스의 고급 액세스 권한으로 업그레이드하세요.

할당량

마케팅 API 액세스	광고 관리 표준 액세스	용량
개발 액세스	표준 액세스	기본 사용 제한 할당량
표준 액세스	고급 액세스	더 높은 사용 제한 할당량

대부분의 마케팅 API 요청과 페이지 API 요청에는 비즈니스 사용 사례(BUC) 사용 제한이 적용되며, 쿼리 대상인 엔드포인트에 좌우됩니다. HTTP 요청에 X-Business-Use-Case 헤더가 포함되어 있는지 확인하면 이를 알아낼 수 있습니다. 자세한 내용은 비즈니스 사용 사례 사용 제한을 참조하세요.

광고 계정 수준 API 수준 제한

사용 제한이 광고 계정 수준에서 적용됩니다.
사용 제한이 일정 시간 범위에서 실시간으로 적용됩니다.
각 마케팅 API 호출에는 점수가 부여되며, 점수는 API 호출의 합계로 계산됩니다.
Facebook에서는 최대 점수를 적용합니다. 일반적으로 읽기 API 호출은 1점이고 쓰기 API 호출은 3점이며, 최대 점수에 도달하면 제한 오류가 발생합니다.
- 앱이 마케팅 API 개발 티어인 경우:
  - 최대 점수는 60점입니다.
  - 감소율은 300초입니다.
  - 최대 점수에 도달하면 300초 동안 차단됩니다.
- 앱이 마케팅 API의 표준 티어인 경우:
  - 최대 점수는 9,000점입니다.
  - 감소율은 300초입니다.
  - 최대 점수에 도달하면 60초 동안 차단됩니다.

관련 오류 코드: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.

광고 계정 수준 QPS 사용 제한

트래픽이 갑자기 급격하게 증가해 시스템에 과부하가 걸리지 않도록 하기 위해 Meta는 마케팅 API 변환 엔드포인트(캠페인, 광고 세트, 광고에 대한 생성 및 수정 작업)에 실시간 사용 제한을 적용합니다.

사용 제한은 앱별로 광고 계정 수준에서 적용됩니다.
제한: 앱 및 광고 계정 조합별로 초당 요청 수(QPS) 100입니다.
적용 대상: 캠페인, 광고 세트 및 광고의 만들기 및 수정 작업입니다.
이 사용 제한은 실시간으로 작동하며, 표준 사용 제한 기간에 감지되지 않을 수 있는 짧은 트래픽 급증을 탐지하도록 설계되었습니다.

영향을 받는 엔드포인트는 다음과 같습니다.

이 제한을 초과하는 경우 요청을 짧은 시간에 집중적으로 보내는 대신 시간을 두고 분산해서 보내세요.

관련 오류 코드: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.

이 오류가 발생하면 요청 제한을 적용하여 광고 계정별 QPS가 100을 초과하지 않도록 하세요.

광고 인사이트 플랫폼 사용 제한

사용 제한이 앱 수준에서 적용됩니다.
사용 제한이 백엔드 인프라와 다운스트림 서비스의 용량에 따라 결정됩니다.
앱에 사용 제한이 적용되면 해당 앱의 모든 광고 인사이트 API 호출이 제한됩니다.
앱 수준 사용 제한이 적용됩니다.

관련 오류 코드:4, Error subcode: 1504022 or 1504039, Message: There have been too many calls from this app. Wait a bit and try again.

이 오류가 발생하면 호출량을 조정하세요.

앱 수준 제한

사용 제한이 앱 수준에서 적용됩니다.
사용 제한이 앱의 총 사용자 수로 결정됩니다.
앱에 사용 제한이 적용되면 해당 앱에 대한 모든 호출이 제한됩니다.
앱 수준 사용 제한이 적용됩니다.

관련 오류 코드:4, Message: Application request limit reached

이 오류가 발생하면 호출량을 조정하세요.

광고 계정 수준 비즈니스 사용 사례 사용 제한

Facebook은 마케팅 API 액세스 티어와 앱에 따라 사용 제한 할당량을 계산합니다.

사용 제한은 광고 계정 수준에서 적용되고 할당량은 앱 광고 API 액세스 티어에 따라 계산됩니다.
ads_management - 1시간 기준 각 광고 계정: (앱이 마케팅 API 표준 티어에 속한 경우 100,000회 또는 앱이 개발 티어에 속한 경우 300회) + 40 * 활성 광고 수.
custom_audience - 1시간 기준 각 광고 계정: 700,000회 이하. 앱이 마케팅 API 표준 티어에 속한 경우 190,000회 이상 또는 앱이 개발 티어에 속한 경우 5,000회 + 40 * 활성 맞춤 타겟 수.
ads_insights - 1시간 기준 각 광고 계정: (앱이 광고 API 표준 티어에 속한 경우 190,000회 또는 앱이 개발 티어에 속한 경우 600회) + 400 * 활성 광고 수 - 0.001 * 사용자 오류.
카탈로그 관리 - 1시간 기준 각 광고 계정: 20,000 + 20,000 * log2(고유 사용자).
카탈로그 배치 - 1시간 기준 각 광고 계정: 200 + 200 * log2(고유 사용자).
마케팅 API 사용 제한은 광고 계정의 총 CPU 시간 및 총 담벼락 시간에 따라 결정할 수도 있습니다. 앱에 마케팅 API 표준 액세스 권한이 있는 경우 더 많은 할당량을 받게 됩니다. 자세한 내용은 HTTP [X-Business-Use-Case](/docs/graph-api/overview/rate-limiting/#headers-2) 헤더 및 비즈니스 사용 사례 사용 제한을 참조하세요.

관련 오류 코드: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.

API 엔드포인트 및 HTTP X-Business-Use-Case 헤더를 확인하여 제한 유형을 확인하세요. 자세한 내용은 비즈니스 사용 사례 사용 제한을 참조하세요. 이 오류가 발생할 경우 광고 계정 변경 사항을 조정하세요.

광고 계정 수준 광고 지출 사용 제한

Facebook에서는 광고 게재 성과를 보장하기 위해 계정 지출 한도 변경을 하루 10회로 제한합니다.

광고 계정 지출(예: spend_cap, spend_cap_action 필드)의 변경 횟수가 제한됩니다.

관련 오류 코드:17, Error subcode: 1885172, Message: You can only change your account spending limit 10 times per day. Please wait to make more changes.

광고 세트 수준 제한

광고 세트 daily_budget 및 lifetime_budget 필드의 변경 횟수가 제한됩니다. 각 광고 세트에서 예산은 한 시간에 4회까지만 변경할 수 있습니다. 이 제한을 초과하는 경우 해당 광고 세트의 예산 변경이 1시간 동안 차단됩니다.

관련 오류 코드:613, Error subcode: 1487632, Message: You can only change your ad set budget 4 times per hour. Please wait to make more changes.

이 오류가 발생할 경우 광고 세트 변경 사항을 조정하세요.

광고 수준 제한

주어진 광고 계정에 대한 광고 만들기가 일일 지출 한도에 따라 제한됩니다.

관련 오류 코드:613, Error subcode: 1487225, Message: User request limit reached.

하위 오류 코드(1487225)와 API 엔드포인트를 통해 제한 유형을 확인하세요. 이 오류가 발생할 경우 변경 사항을 다시 조정하세요. 또한 한도를 높이기 위해 일일 지출 한도를 높일 수도 있습니다.

악용 사례 방지 사용 제한

Facebook 시스템에서 특정 광고 계정이 대량의 비정상적인 트래픽을 유발하는 것을 탐지하는 경우, 시스템 안정성을 보호하고 다른 사용자의 경험을 보장하기 위해 비정상적인 계정의 API 사용 제한 할당량을 일시적으로 낮춥니다. Meta 지원팀에 문의하여 도움을 요청하세요.

관련 오류 코드:613, Error subcode: null, Message: (#613) Calls to this api have exceeded the rate limit.

이 제한과 광고 계정 수준 API 수준 제한의 차이점은 이 오류에는 오류 하위 코드가 포함되지 않는다는 것입니다. 이 오류가 발생할 경우 과도한 API 요청을 트리거하는 행동이 있는지 조사하고 Meta 지원팀에 문의하여 도움을 요청하세요.

제한 오류 처리

초기 평가

마케팅 API 액세스 티어 확인:

기본적으로 앱은 마케팅 API에 대한 development_access가 있습니다. 어떤 티어에 속해 있는지 확인하려면 앱 검수 대시보드를 참조하세요. 광고 관리 표준 액세스 기능에 대한 표준 액세스 권한을 가지고 있는 경우, 마케팅 API 액세스의 개발 티어에 속한 것입니다. 광고 관리 표준 액세스 기능에 대한 고급 액세스 권한을 가지고 있는 경우, 마케팅 API 액세스의 표준 티어에 속한 것입니다. HTTP 헤더를 확인하고 X-Ad-Account-Usage, X-Business-Use-Case 또는 X-FB-Ads-Insights-Throttle 헤더에서 ads_api_access_tier를 찾아볼 수도 있습니다.

사용 제한 오류가 계속 발생하는 경우 광고 관리 표준 액세스의 standard_access로 업그레이드하는 것이 좋습니다. 표준 티어로 업그레이드하고 더 높은 사용 제한 할당량을 받으려면 앱 검수 대시보드에서 광고 관리 표준 액세스 기능에 대한 고급 액세스를 신청하면 됩니다.

오류 코드 확인: API 응답에서 제한과 관련된 특정 오류 코드를 확인합니다.
HTTP 헤더 확인:
- X-Ad-Account-Usage에 acc_id_util_pct, reset_time_duration 및 ads_api_access_tier가 있습니다.
- 비즈니스 사용 사례 엔드포인트에 대해 X-Business-Use-Case에 call_count, total_cputime, total_time 및 estimated_time_to_regain_access 등의 정보가 있습니다.
- 광고 인사이트 API 엔드포인트에 대해 X-FB-Ads-Insights-Throttle에 app_id_util_pct, acc_id_util_pct 및 ads_api_access_tier가 있습니다.
앱 대시보드 확인: Facebook에서는 앱 대시보드에 개발자에게 사용 제한 시스템에 대한 심층적 인사이트를 제공하고 개발자가 사용 제한 문제를 진단하고 예방하는 데 도움을 주는 콘솔을 제공합니다.

원인 파악

사용 제한: 사용 중인 다양한 엔드포인트의 Meta 마케팅 API 사용 제한을 파악하고 API 요청 수가 해당 앱에 허용되는 한도 이내인지 확인합니다.
버스트 제한: 사용량이 많은 시간대에 버스트 제한 때문에 문제가 발생하는지 확인합니다. 대개 버스트 트래픽이 광고 계정 수준 API 수준 제한을 발생시킵니다(관련 오류 코드:17, 613).
오작동: 오작동 때문에 과도한 API 요청이 트리거되는지 조사합니다.

완화 단계

버스트 트래픽 방지: API 요청을 균등하게 배분하여 단시간 내 대량 액세스로 인한 제한이 발생하지 않도록 합니다.
요청 최적화: 여러 개의 작은 요청을 일괄 요청(ID 배치 또는 비동기식 요청)으로 결합하여 총 API 호출 횟수를 최소화합니다.
백오프 전략: 제한 오류를 수신했을 때 기하급수적 백오프를 구현하여 재시도 사이의 시간을 점진적으로 늘립니다. 재설정 시간 추정을 위해 HTTP 헤더를 검사할 수도 있습니다.

기타 완화 팁

호출이 필요한지 확인하고 불필요하다면 해당 호출을 줄입니다.
광고 인사이트 API와 같이 비동기식 요청을 지원하는 엔드포인트의 경우 비동기식 요청을 사용하여 대량의 데이터를 쿼리합니다.
동일한 유형의 광고 개체를 여러 개 쿼리해야 할 경우 ID 리스트를 전달하는 방법도 사용할 수 있습니다.
인사이트 API의 경우 레벨 매개변수 또는 필터링을 사용하여 호출 수를 줄입니다.