사용 제한

사용 제한이란 주어진 시간 동안 앱이나 사용자에게 허용된 API 호출 수를 말합니다. 이 제한을 초과하거나 CPU 또는 전체 시간 제한을 초과하면 해당 앱이나 사용자가 제한될 수 있습니다. 제한된 사용자나 앱이 보낸 API 요청은 실패합니다.

모든 API 요청에 사용 제한이 적용됩니다. 그래프 API와 Instagram 기본 디스플레이 API 요청의 경우 플랫폼 사용 제한이 적용되고, 마케팅 API와 Instagram 그래프 API 요청에는 비즈니스 사용 사례(BUC) 사용 제한이 적용됩니다.

페이지 API 요청의 경우 요청에 사용된 토큰에 따라 플랫폼 또는 BUC 사용 제한이 적용됩니다. 즉 앱 또는 사용자 액세스 토큰을 사용한 요청은 플랫폼 사용 제한이 적용되고, 시스템 사용자 또는 페이지 액세스 토큰을 사용한 요청은 비즈니스 사용 사례 사용 제한이 적용됩니다.

실시간 사용 제한 사용 통계가 헤더에 설명되며, 헤더는 어느 엔드포인트에 충분히 호출을 보내면 대부분의 API 응답에 포함됩니다. 플랫폼 사용 제한 사용 통계는 앱 대시보드에도 표시됩니다. 사용 제한에 도달하면 앱이 보내는 이후의 모든 요청이 실패하고 호출 수가 제한 미만으로 떨어질 정도로 시간이 충분히 결과할 때까지 API가 오류 코드를 반환합니다.

한 가지 요청에 플랫폼 및 사용 사례 사용 제한이 둘 다 적용되는 경우 BUC 사용 제한이 적용됩니다.

플랫폼 사용 제한

플랫폼 사용 제한은 요청에 사용된 토큰 유형에 따라 각 앱 또는 사용자 수준에서 추적됩니다.

앱

앱 액세스 토큰을 사용한 그래프 API 요청은 해당 앱의 사용 제한에 반영됩니다. 앱의 호출 수는 앱이 1시간 동안 보낼 수 있는 호출 횟수이며, 계산 방법은 다음과 같습니다.

사용자 수는 앱이 보유한 고유 일일 액티브 사용자 수를 기준으로 합니다. 일일 사용량이 적은 기간이 있는 경우(예를 들어 앱 활동량이 주말에는 많지만 평일에는 적은 경우) 앱의 사용자 수를 계산할 때 주간 및 월간 액티브 사용자를 사용합니다. 일일 참여가 높은 앱은 실제 앱 설치 수와 관계없이 일일 참여가 낮은 앱보다 높은 사용 제한이 적용됩니다.

이것은 사용자 1인당 제한이 아니라 앱이 보내는 호출에 적용되는 제한입니다. 모든 개인 사용자는 앱을 사용하여 시간당 200회 이상의 호출을 보낼 수 있으나 앱에서 보내는 호출의 총합이 해당 앱의 최댓값을 초과하지 않아야 합니다. 예를 들어 앱의 사용자가 100명이면 앱에서 시간당 20,000회의 호출을 보낼 수 있습니다. 하지만 참여가 가장 활발한 상위 10명의 사용자는 해당 호출 중 19,000회를 사용할 수 있습니다.

사용자

사용자 액세스 토큰을 사용한 그래프 API 요청은 사용자의 호출 수에 반영됩니다. 사용자의 호출 수는 한 사용자가 한 시간 동안 보낼 수 있는 호출 수를 의미합니다. 개인정보 보호 문제로 인해 사용자의 실제 호출 수 값은 공개하지 않습니다.

사용자의 호출 수는 여러 앱에 분산될 수 있습니다. 예를 들어 사용자 한 명이 App1에서 X회, App2에서 Y회의 호출을 보낼 수 있습니다. X+Y 값이 해당 사용자의 호출 수를 초과하면 그 사용자는 사용이 제한됩니다. 그렇다고 앱에 문제가 있다는 뜻은 아닙니다. 사용자가 여러 개의 앱을 사용하고 있거나 API를 잘못 사용하고 있다는 뜻일 수 있습니다.

헤더

앱에서 충분히 요청을 수신한 엔드포인트는 응답에 X-App-Usage 또는 X-Ad-Account-Usage(v3.3 이전 광고 API 호출의 경우) HTTP 헤더를 포함합니다. 이 헤더에 JSON 형식의 문자열을 포함하여 현재 앱 사용 제한 사용량을 표시합니다.

헤더 내용

X-Ad-Account-Usage 헤더 콘텐츠

전체 CPU 시간

요청을 처리하는 데 소요되는 CPU 시간. total_cputime이 100에 도달하면 호출이 제한될 수 있습니다.

전체 시간

요청을 처리하는 데 소요되는 시간. total_time이 100에 도달하면 호출이 제한될 수 있습니다.

X-App-Usage 헤더 값 샘플

x-app-usage: {
    "call_count": 28,         //Percentage of calls made 
    "total_time": 25,         //Percentage of total time
    "total_cputime": 25       //Percentage of total CPU time
}

X-Ad-Account-Usage 헤더 값 샘플

x-ad-account-usage: {
    "acc_id_util_pct": 9.67,   //Percentage of calls made for this ad account.
    "reset_time_duration": 100,   //Time duration (in seconds) it takes to reset the current rate limit score.
    "ads_api_access_tier": 'standard_access'   //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
}

대시보드

앱 대시보드는 사용이 제한된 앱 사용자 수, 앱의 현재 앱 사용 제한 사용량 비율, 최근 7일간의 평균 활동량을 표시합니다. 앱 사용 제한 카드에서 세부 정보 보기를 클릭하고 그래프에 있는 점에 커서를 가져가면 특정 시점의 사용량에 대한 자세한 정보를 확인할 수 있습니다. 사용량은 호출량에 따라 달라지기 때문에 이 그래프는 7일 전체가 표시되지 않을 수 있습니다. 호출량이 많은 앱은 더 많은 날짜가 표시됩니다.

오류 코드

앱이나 사용자가 사용 제한에 도달하면 해당 앱이나 사용자가 보낸 요청은 실패하고 API가 오류 코드로 응답합니다.

제한 오류 코드

응답 샘플

{
  "error": {
    "message": "(#32) Page request limit reached",
    "type": "OAuthException",
    "code": 32,
    "fbtrace_id": "Fz54k3GZrio"
  }
}

Facebook 안정성 제한 코드

모범 사례

• 제한에 도달하면 API 호출을 중단하세요. 계속 호출하면 호출 수가 계속 늘어나고, 따라서 호출에 다시 성공할 때까지 걸리는 시간도 늘어납니다.
• 쿼리를 균일하게 분산하여 트래픽 급증을 피하세요.
• 필터를 사용해 데이터 응답 크기를 제한하고, 겹치는 데이터를 요청하는 호출을 피하세요.
• X-App-Usage HTTP 헤더에서 앱이 얼마나 제한에 가까워졌는지, 제한에 도달한 경우 언제 호출을 다시 보낼 수 있는지 확인하세요.
• 사용자가 제한된 경우 앱 문제가 아닌지 확인하세요. 해당 사용자의 호출을 줄이거나 사용자의 호출이 시간의 흐름에 따라 균일하게 분산되도록 합니다.

비즈니스 사용 사례 사용 제한

시스템 또는 페이지 액세스 토큰으로 요청한 모든 마케팅 API 요청과 페이지 API 요청에는 비즈니스 사용 사례(BUC) 사용 제한이 적용되며, 쿼리하는 엔드포인트에 좌우됩니다.

마케팅 API의 경우 동일한 비즈니스 사용 사례에 걸쳐 사용 제한이 광고 계정에 적용됩니다. 예를 들어 광고 관리 비즈니스 사용 사례를 사용하는 모든 엔드포인트는 동일한 광고 계정 내에서 전체 할당량을 공유합니다. 특정 엔드포인트가 대량의 API 요청을 보내서 제한이 적용될 경우, 동일한 비즈니스 사용 사례로 구성된 다른 엔드포인트에도 사용 제한 오류가 적용됩니다. 할당량은 앱의 마케팅 API 액세스 등급에 따라 달라집니다. 표준 액세스 마케팅 API 계층은 개발 액세스 마케팅 API 계층보다 할당량이 더 많습니다. 기본적으로 새 앱은 개발 계층에 있어야 합니다. 더 높은 사용 제한 할당량으로 업그레이드해야 할 경우 앱 검수에서 광고 관리 표준 액세스의 고급 액세스로 업그레이드하세요.

광고 인사이트

앱에서 광고 인사이트 API로 보낸 요청은 호출 횟수, 총 CPU 시간, 총 시간 등과 같은 앱 사용 제한 지표에 반영됩니다. 앱의 호출 수는 앱이 1시간 동안 보낼 수 있는 호출 횟수이며, 계산 방법은 다음과 같습니다.

광고 관리 표준 액세스 기능에 대한 표준 액세스 권한이 있는 앱:

광고 관리 표준 액세스 기능에 대한 고급 액세스 권한이 있는 앱:

활성 광고 수는 현재 광고 계정당 게재되는 광고 수입니다. 사용자 오류는 API를 호출할 때 수신한 오류 수입니다. 사용 제한을 높이려면 광고 관리 표준 액세스 기능을 신청하세요.

사용 제한은 1시간 동안의 총 CPU 시간과 총 실제 시간에 따라 달라질 수도 있습니다. 자세한 내용은 HTTP X-Business-Use-Case 헤더 total_cputime 및 total_time을 참조하세요.

또한 사용 제한 오류가 발생할 경우 X-Business-Use-Case 헤더의 estimated_time_to_regain_access에서 예상 차단 시간을 참조하세요.

광고 관리

앱에서 광고 관리 API로 보낸 요청은 호출 횟수, 총 CPU 시간, 총 시간 등과 같은 앱 사용 제한 지표에 반영됩니다. 앱의 호출 수는 앱이 1시간 동안 보낼 수 있는 호출 횟수이며, 계산 방법은 다음과 같습니다.

광고 관리 표준 액세스 기능에 대한 표준 액세스 권한이 있는 앱:

광고 관리 표준 액세스 기능에 대한 고급 액세스 권한이 있는 앱:

활성 광고 수는 각 광고 계정의 광고 수입니다.

사용 제한은 1시간 동안의 총 CPU 시간과 총 실제 시간에 따라 달라질 수도 있습니다. 자세한 내용은 HTTP X-Business-Use-Case 헤더 total_cputime 및 total_time을 참조하세요.

또한 사용 제한 오류가 발생할 경우 X-Business-Use-Case 헤더의 estimated_time_to_regain_access에서 예상 차단 시간을 참조하세요.

카탈로그

카탈로그 배치

앱에서 보낸 요청은 각 카탈로그 ID당 1시간 동안 앱이 보낼 수 있는 호출 횟수, 총 CPU 시간, 총 시간 등의 사용 제한 지표에 반영됩니다.

고유 사용자는 최근 28일 동안 (모든 카탈로그에서) 인텐트가 있는 비즈니스의 고유 사용자 수를 말합니다. 카탈로그에서 제품을 보는 사용자가 늘어날수록 호출 할당량이 더 많이 할당됩니다.

카탈로그 관리

앱에서 보낸 요청은 앱이 각 카탈로그 ID에 대해 1시간 동안 보낼 수 있는 호출 횟수에 반영되며 계산 방법은 다음과 같습니다.

고유 사용자는 최근 28일 동안 (모든 카탈로그에서) 인텐트가 있는 비즈니스의 고유 사용자 수를 말합니다. 카탈로그에서 제품을 보는 사용자가 늘어날수록 호출 할당량이 더 많이 할당됩니다.

이 공식은 다양한 카탈로그 엔드포인트에 적용됩니다.

현재 사용량을 가져오는 방법에 대한 자세한 내용은 헤더를 참조하세요.

사용 제한은 1시간 동안의 총 CPU 시간과 총 실제 시간에 따라 달라질 수도 있습니다. 자세한 내용은 HTTP X-Business-Use-Case 헤더 total_cputime 및 total_time을 참조하세요.

또한 사용 제한 오류가 발생할 경우 X-Business-Use-Case 헤더의 estimated_time_to_regain_access에서 예상 차단 시간을 참조하세요.

맞춤 타겟

앱에서 맞춤 타겟 API로 보낸 요청은 호출 횟수, 총 CPU 시간, 총 시간 등과 같은 앱 사용 제한 지표에 반영됩니다. 앱의 호출 수는 앱이 1시간 동안 보낼 수 있는 호출 횟수이며, 계산 방법은 다음과 같습니다(단, 700,000회를 초과할 수 없음).

광고 관리 표준 액세스 기능에 대한 표준 액세스 권한이 있는 앱:

광고 관리 표준 액세스 기능에 대한 고급 액세스 권한이 있는 앱:

활성 맞춤 타겟 수는 각 광고 계정의 활성 맞춤 타겟 수입니다.

사용 제한은 1시간 동안의 총 CPU 시간과 총 실제 시간에 따라 달라질 수도 있습니다. 자세한 내용은 HTTP X-Business-Use-Case 헤더 total_cputime 및 total_time을 참조하세요.

또한 사용 제한 오류가 발생할 경우 X-Business-Use-Case 헤더의 estimated_time_to_regain_access에서 예상 차단 시간을 참조하세요.

Instagram 그래프 API

Instagram 그래프 API에 대한 호출은 앱 호출 수에 반영됩니다. 앱의 호출 수는 각 앱과 앱 사용자 쌍에 대해 고유하며, 이 수는 앱이 24시간 동안 보낸 호출 수를 의미합니다. 계산 방법은 다음과 같습니다.

노출 횟수는 최근 24시간 내에 앱 사용자의 Instagram 계정에 게시된 각종 콘텐츠가 다른 사람의 화면에 들어간 횟수입니다.

참고

• Instagram 기본 디스플레이 API는 플랫폼 사용 제한을 사용합니다.
• 비즈니스 검색과 해시태그 검색에는 플랫폼 사용 제한이 적용됩니다.

LeadGen

앱이 잠재 고객 확보 API로 보낸 요청은 해당 앱의 호출 수에 반영됩니다. 앱의 호출 수는 앱이 24시간 동안 보낼 수 있는 호출 횟수이며, 계산 방법은 다음과 같습니다.

확보된 잠재 고객 수는 이 광고 계정이 최근 90일 동안 페이지당 확보한 잠재 고객 수입니다.

Messenger 플랫폼

페이지

페이지 사용 제한은 사용한 토큰 유형에 따라 플랫폼 사용 제한 로직이나 BUC 사용 제한 로직을 사용할 수 있습니다. 페이지 또는 시스템 사용자 액세스 토큰을 사용한 모든 페이지 API 호출은 아래의 사용 제한 계산법을 사용합니다. 앱 또는 사용자 액세스 토큰을 사용한 호출에는 앱 또는 사용자 사용 제한이 적용됩니다.

앱이 페이지 액세스 토큰이나 시스템 사용자 액세스 토큰을 사용하여 페이지 API에 보낸 요청은 해당 앱의 호출 수에 반영됩니다. 앱의 호출 수는 앱이 24시간 동안 보낼 수 있는 호출 횟수이며, 계산 방법은 다음과 같습니다.

참여 사용자 수는 24시간 기준으로 페이지에 참여한 사용자 수입니다.

앱이 사용자 액세스 토큰이나 앱 액세스 토큰을 사용하여 페이지 API에 보낸 요청은 플랫폼 사용 제한 로직을 따릅니다.

페이지 전체 공개 액세스 콘텐츠 기능을 사용할 때 사용 제한 문제를 방지하려면 시스템 사용자 액세스 토큰을 사용하는 것이 좋습니다.

Spark AR 커머스 효과 관리

앱이 커머스 엔드포인트로 보낸 요청은 앱의 호출 수에 반영됩니다. 앱의 호출 수는 앱이 1시간 동안 보낼 수 있는 호출 횟수이며, 계산 방법은 다음과 같습니다.

카탈로그 수는 앱에서 관리하는 모든 커머스 계정의 카탈로그 수 합계입니다.

WhatsApp Business Management API

헤더

BUC 로직을 사용하여 사용 제한이 적용되는 앱의 모든 API 응답에는 현재 앱 사용 제한 사용량을 나타내는 JSON 형식 문자열이 있는 X-Business-Use-Case-Usage(v3.3 이하 광고 API 호출의 경우) HTTP 헤더가 포함됩니다. 이 헤더는 한 번의 호출에 최대 32개의 개체를 반환할 수 있습니다.

X-Business-Use-Case-Usage 헤더 내용

전체 CPU 시간

요청을 처리하는 데 소요되는 CPU 시간. total_cputime이 100에 도달하면 호출이 제한될 수 있습니다.

전체 시간

요청을 처리하는 데 소요되는 시간. total_time이 100에 도달하면 호출이 제한될 수 있습니다.

광고 API 액세스 계층

ads_insights 및 ads_management 유형에만 적용됩니다. 계층(Tier)은 앱에서 마케팅 API에 액세스할 수 있도록 합니다. 기본적으로 앱은 development_access 계층에 있습니다. Standard_access는 더 낮은 사용 제한을 지원합니다. 사용 제한을 높이고 표준 계층으로 올라가려면 광고 관리 표준 액세스 기능에 대한 '고급 액세스 권한'을 신청할 수 있습니다.

X-Business-Use-Case-Usage 헤더 값 샘플

x-business-use-case-usage: {
    "{business-object-id}": [
        {
            "type": "{rate-limit-type}",           //Type of BUC rate limit logic being applied.
            "call_count": 100,                     //Percentage of calls made. 
            "total_cputime": 25,                   //Percentage of the total CPU time that has been used.
            "total_time": 25,                      //Percentage of the total time that has been used.   
            "estimated_time_to_regain_access": 19,  //Time in minutes to regain access.
            "ads_api_access_tier": "standard_access"  //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
        }
    ],      
    "66782684": [
        {
            "type": "ads_management",
            "call_count": 95,
            "total_cputime": 20,
            "total_time": 20,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access" 
        }
    ],
    "10153848260347724": [
        {
            "type": "ads_insights",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access"
        }
    ],
    "10153848260347724": [
        {
            "type": "pages",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0
        }
    ],
...
}

오류 코드

앱이 비즈니스 사용 사례 사용 제한에 도달하면 그 이후에 앱이 보내는 요청은 실패하고 API가 오류 코드로 응답합니다.

샘플 오류 코드 메시지

{   
"error": {      
    "message": "(#80001) There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.",      
    "type": "OAuthException",      
    "code": 80001,      
    "fbtrace_id": "AmFGcW_3hwDB7qFbl_QdebZ"   
    }
}

모범 사례

• 제한에 도달하면 API 호출을 중단하세요. 계속 호출하면 호출 수가 계속 늘어나고, 따라서 호출에 다시 성공할 때까지 걸리는 시간도 늘어납니다.
• X-Business-Use-Case-Usage HTTP 헤더를 통해 광고 계정이 제한에 어느 정도 도달했는지, 언제 호출을 다시 시작할 수 있는지 확인하세요.
• 오류 코드와 API 엔드포인트를 통해 제한 유형을 확인하세요.
• 다른 광고 계정으로 전환한 후 나중에 이 계정으로 다시 돌아오세요.
• 기존 광고를 변경하기보다 새로운 광고를 만드는 것이 좋습니다.
• 전송 트래픽이 폭주하는 현상이 발생하지 않도록 쿼리를 두 기간 사이에 균일하게 분산하세요.
• 필터를 사용해 데이터 응답 크기를 제한하고, 겹치는 데이터를 요청하는 호출을 피하세요.

FAQ

API 호출로 간주되는 항목은?

모든 호출 수는 각각의 API 요청만이 아니라 사용 제한에 대해서도 카운트됩니다. 예를 들어 여러 ID를 지정한 API 호출을 한 번 보내더라도 각 ID는 하나의 API 호출로 계산됩니다.

다음 표는 이 개념을 나타냅니다.

가능하면 한 번의 API 요청에 여러 ID를 지정하는 것이 좋습니다. 이렇게 하면 API 응답의 성능이 개선됩니다.

스크래퍼를 만들 때 어떤 사항을 고려해야 하나요?

데이터를 스크래핑하는 서비스를 빌드하는 경우에는 Facebook의 스크래핑 용어를 읽어보세요.