API 한도 및 할당량

Google Ads API는 단일 mutate 요청에서 전송할 수 있는 작업 수와 같은 API 작업을 제한합니다. 다음 표에는 알아두어야 할 몇 가지 중요한 한도와 할당량이 요약되어 있습니다.

요청 유형, 제한사항, 오류 코드
기본 액세스 수준 작업 일일 API 작업 15,000회 RESOURCE_EXHAUSTED
변경 요청 요청당 작업 10,000개 TOO_MANY_MUTATE_OPERATIONS
계획 서비스 요청 1QPS RESOURCE_EXHAUSTED
전환 업로드 서비스 요청 요청당 2,000건의 전환 TOO_MANY_CONVERSIONS_IN_REQUEST
결제 및 계정 예산 서비스 요청 변경 요청당 1개의 작업 TOO_MANY_MUTATE_OPERATIONS

일일 API 작업 한도

일일 API 사용량 한도는 개발자 토큰당 실행된 API 작업 수를 기준으로 합니다. API 작업은 가져오기 요청과 변이 작업의 총합입니다. 일일 API 작업의 한도는 개발자 토큰의 액세스 수준에 따라 다릅니다. 액세스 수준 및 허용되는 사용 가이드에는 각 액세스 수준의 구체적인 API 작업 한도가 설명되어 있습니다.

이러한 한도를 위반하는 요청은 RESOURCE_EXHAUSTED 오류와 함께 거부됩니다.

gRPC 제한사항

모든 Google Ads API 클라이언트 라이브러리는 gRPC를 사용하여 요청과 응답을 생성합니다. 기본적으로 gRPC의 메시지 크기는 4MB이지만, 효율성을 높이기 위해 클라이언트 라이브러리는 최대 메시지 크기를 64MB로 설정합니다.

대답은 이 한도를 초과해서는 안 됩니다. 예를 들어 필드가 많이 포함된 검색 요청은 크기가 64MB를 초과하는 응답을 생성할 수 있습니다. 이 한도를 피하려면 선택한 필드 수를 줄이거나 스트리밍을 사용하세요. 변경의 경우 요청당 작업 수를 줄입니다.

이 제한을 위반하는 요청은 GoogleAdsError을 생성하지 않지만 429 Resource Exhausted gRPC 오류를 생성합니다. gRPC 오류 코드 및 메시지 목록을 참고하세요.

변경 요청

사용자의 일일 작업 할당량에 포함되는 것 외에도 mutate 요청에는 요청당 10,000개 이상의 작업이 포함될 수 없습니다.

이 제한을 위반하는 요청은 TOO_MANY_MUTATE_OPERATIONS 오류와 함께 거부됩니다.

특정 서비스 및 요청 유형에 대한 추가 제한사항 및 고려사항은 다음에 설명되어 있습니다.

요청 검색

Search 또는 SearchStream 요청은 사용자 일일 작업 할당량에 대해 하나의 작업으로 계산됩니다. SearchStream 요청 하나는 배치 수와 관계없이 API 작업 하나로 계산됩니다.

페이지로 나눈 요청

페이지로 나누어진 요청 (예: 유효한 next_page_token가 포함된 요청)은 사용자의 일일 작업 할당량에 포함되지 않습니다. 하지만 만료되었거나 유효하지 않은 페이지 토큰이 포함된 페이지로 나누기 요청은 예외를 생성하며 일일 작업 할당량에 포함됩니다.

페이지로 나누기에 관한 자세한 내용은 결과 페이지로 나누기를 참고하세요.

기타 유형의 요청

Get, Mutate, Search 또는 SearchStream 요청이 아닌 요청은 사용자의 일일 작업 할당량에 대해 하나의 작업으로 계산됩니다.

이러한 요청의 몇 가지 예는 다음과 같습니다.

API 예외를 반환하는 요청

GoogleAdsFailure로 거부된 요청은 여전히 사용자의 일일 작업 할당량에 포함됩니다.

실패했지만 GoogleAdsFailure를 반환하지 않는 요청(예: 네트워크 수준의 오류로 인한 요청)은 서비스에 도달하지 않으므로 사용자의 일일 작업 할당량에 포함되지 않습니다. 네트워크 연결 실패가 그 예입니다.

키워드 계획 서비스

비용과 복잡성으로 인해 다음 키워드 계획 서비스 메서드는 다른 유형의 요청과 별도의 제한이 적용됩니다.

키워드 계획을 만들 때 다음 제한사항에 유의하세요.

키워드 계획 객체 최대 수
계정당 KeywordPlan 10,000
KeywordPlan당 KeywordPlanAdGroup 200
KeywordPlan당 KeywordPlanAdGroupKeyword 10,000
KeywordPlanCampaignKeyword (제외 키워드) 1,000
KeywordPlan당 KeywordPlanCampaign 1

잠재고객 통계 서비스

AudienceInsightsService 메서드 내의 다음 메서드에는 특정 할당량 한도가 적용됩니다.

전환 업로드 서비스

전환 조정 업로드 서비스

결제 및 계정 예산 서비스

  • 변경은 월별 인보이스로 구성된 계정에 대해서만 가능합니다.

    이 제한을 위반하는 요청은 MUTATE_NOT_ALLOWED 오류와 함께 거부됩니다.

  • 변이 요청에는 1개의 작업만 허용됩니다.

    이 제한을 위반하는 요청은 TOO_MANY_MUTATE_OPERATIONS 오류와 함께 거부됩니다.

  • 동일한 계정의 예산 주문을 변경할 때는 최소 12시간이 지나야 합니다. 12시간이 지나기 전에 변경하면 복구할 수 없는 오류가 발생할 수 있으며, 이 오류는 Google Ads 계정 담당자만 해결할 수 있습니다.

고객 계정 초대

신규 사용자는 CustomerUserAccessService를 사용하여 기존 고객 계정에 초대할 수 있습니다. 이 기능은 다른 사용자에게 초대 이메일을 전송하므로 악용될 가능성이 있어 다음과 같은 제한사항이 있습니다.

사용자 데이터

사용자 데이터는 UserDataService 및 OfflineUserDataJobService로 관리됩니다. 지정된 생성 또는 삭제 UserData 작업에서 각 user_identifiers 세트는 단일 사용자에게만 적용되어야 합니다.

이를 적용하기 위해 UserData 세트에 user_identifiers가 20개를 초과하는 경우 OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS 또는 UserDataError.TOO_MANY_USER_IDENTIFIERS 오류가 반환됩니다.

작업 수와 관계없이 최대 100,000개의 사용자 식별자가 허용됩니다.

기타 유형의 한도

요청에 항목이 너무 많은 작업 목록과 같은 반복 필드는 REQUEST_SIZE_LIMIT_EXCEEDED 오류가 발생할 수 있습니다. 이 오류 메시지는 다른 문제로 인해 발생할 수도 있습니다.

이 제한이 발생하고 반복 필드를 사용하는 요청을 하는 경우 변이 요청에서 작업 목록을 배포하여 반복 필드의 항목 수를 줄여 보세요.

GAQL 쿼리를 실행할 때 IN 절 내의 최대 항목 수는 20,000개입니다. 이 한도를 초과하면 FILTER_HAS_TOO_MANY_VALUES 오류가 반환됩니다.

이전
개요
다음
시스템 한도