프로덕션 애플리케이션과 AI 에이전트에서 Developer Knowledge API 또는 Developer Knowledge MCP 서버를 쿼리할 때는 높은 성능을 달성하기 위해 오류 처리 및 할당량 관리가 있어야 합니다.
이 가이드에서는 다음 작업을 수행하는 방법을 배웁니다.
- HTTP 429 응답에 지터가 포함된 잘린 지수 백오프를 구현합니다.
- 표준 gRPC 오류 코드 (
INVALID_ARGUMENT,PERMISSION_DENIED,RESOURCE_EXHAUSTED)를 처리합니다. - MCP 연결 제한 시간 및 재시도 로직을 관리합니다.
- 할당량 관리 및 캐싱 권장사항을 적용합니다.
HTTP 429 비율 제한 및 지수 백오프
요청 비율이 기본 API 할당량을 초과하면 서비스에서 HTTP 429 Too Many Requests 오류를 반환합니다. 애플리케이션은 서비스에 과부하가 걸리지 않도록 지터링을 사용하여 잘린 지수 백오프를 사용하는 재시도 로직을 구현해야 합니다.
잘린 지수 백오프
다음 공식을 사용하여 재시도 지연 시간을 계산합니다.
retry_delay = min(max_delay, initial_delay * (2 ^ attempt) + jitter)
다음 매개변수를 사용하여 재시도 지연 시간을 계산합니다.
initial_delay: 초기 재시도 지연 시간 (예: 1.0초)max_delay: 최대 백오프 한도 (예: 32.0초)attempt: 현재 재시도 횟수 (0, 1, 2, …)입니다.jitter: 스레드 동기화 급증 (우르르 몰려드는 문제)을 방지하기 위한 0~1.0초 사이의 임의 값입니다.
gRPC 오류 처리
gRPC를 통해 서비스에 액세스하는 애플리케이션은 표준 grpc.StatusCode 값을 검사해야 합니다.
표준 gRPC 상태 코드
다음 표에는 서비스에서 반환하는 표준 gRPC 상태 코드와 권장되는 클라이언트 처리가 나와 있습니다.
| gRPC 상태 코드 | HTTP 상태 | 근본 원인 | 권장 조치 |
|---|---|---|---|
INVALID_ARGUMENT |
400 Bad Request |
잘못된 쿼리 문자열, 잘못된 매개변수 형식 또는 잘못된 필드 마스크입니다. | 다시 시도하지 마세요. 반복하기 전에 요청 매개변수를 수정하세요. |
UNAUTHENTICATED |
401 Unauthorized |
API 키 또는 OAuth Bearer 토큰이 누락되었거나, 만료되었거나, 형식이 잘못되었습니다. | 다시 시도하지 마세요. 사용자 인증 정보를 새로고침하거나 유효한 API 키를 생성합니다. |
PERMISSION_DENIED |
403 Forbidden |
API 키에 권한이 없거나 프로젝트에서 Developer Knowledge API가 사용 중지되어 있습니다. | 다시 시도하지 마세요. Google Cloud 콘솔에서 API 사용 설정 여부를 확인합니다. |
NOT_FOUND |
404 Not Found |
지정된 parent 문서 경로가 없습니다. 요청된 문서가 하나라도 없으면 BatchGetDocuments가 원자적으로 실패합니다. |
다시 시도하지 마세요. 문서 리소스 이름을 확인합니다. |
RESOURCE_EXHAUSTED |
429 Too Many Requests |
비율 제한 또는 프로젝트 할당량 한도를 초과했습니다. | 지터와 함께 지수 백오프를 사용하여 다시 시도합니다. |
UNAVAILABLE |
503 Service Unavailable |
일시적인 네트워크 연결 해제 또는 서버 재시작 | 지수 백오프로 다시 시도합니다. |
DEADLINE_EXCEEDED |
504 Gateway Timeout |
요청이 완료되기 전에 구성된 RPC 기한을 초과했습니다. | 클라이언트 RPC 제한 시간을 늘려 다시 시도하세요. |
MCP 연결 시간 제한 및 오류 관리
개발자 지식 MCP 서버는 https://developerknowledge.googleapis.com/mcp에서 호스팅되는 원격 서비스로, HTTPS를 통해 액세스합니다 (HTTP POST 또는 서버 전송 이벤트 사용). AI 호스트와 에이전트는 연결 시간 제한과 도구 오류를 적절하게 관리해야 합니다.
도구 실행 제한 시간
에이전트가 search_documents, get_documents 또는 answer_query를 호출할 때 네트워크 연결이 지연되면 도구 호출이 시간 제한 기간 (예: 30초)을 초과할 수 있습니다.
도구 실행 시간 제한을 처리하려면 다음 단계를 따르세요.
- 클라이언트 제한 시간 구성: MCP 호스트 클라이언트 구성에서 도구 실행 제한 시간을 30~60초로 설정합니다.
- 네트워크 중단 처리: 일시적인 네트워크 중단이나 HTTP 503 응답이 발생하면 지수 백오프로 실패한 HTTP 요청을 재시도합니다.
- 오류 메시지 검사: 표준 JSON-RPC 오류 메시지 또는 HTTP 오류 상태 코드를 파싱하여 잘못된 인수와 할당량 소진을 구분합니다.
할당량 관리 권장사항
최적의 API 사용을 유지하고 예기치 않은 비율 제한을 방지하려면 다음 권장사항을 따르세요.
- 검색된 문서 콘텐츠 캐시: 동일한 페이지에 자주 액세스하는 애플리케이션을 빌드할 때 가져온 마크다운 문서를 로컬 또는 캐시 (예: Redis)에 저장합니다.
- 일괄 검색 사용: 여러 개의 순차적
documents.get요청을 실행하는 대신documents.batchGet를 사용합니다. - 쿼리 필드 최적화: 선택적 필드 마스크(
fields=results(parent,content))를 사용하여 필수 응답 필드만 요청합니다. - 할당량 소비 모니터링: Google Cloud 콘솔 API 대시보드에서 API 요청률을 추적합니다.