SerpBase

응답과 오류

모든 응답은 같은 구조의 JSON입니다. 성공 여부는 HTTP 상태가 아니라 status 필드로 판단한 뒤 결과를 읽으세요.

공통 응답 구조

성공 응답은 동일한 최상위 메타데이터를 반환합니다. 엔드포인트별 데이터는 organic, images, news, videos, places, place 같은 결과 키에 들어갑니다.

status
필수
number

필수

비즈니스 상태 코드입니다. 0은 성공을 의미합니다.

request_id
필수
string

필수

지원, 재시도, 로그 추적에 사용하는 요청 ID입니다.

elapsed_ms
필수
number

필수

게이트웨이가 측정한 요청 실행 시간(ms)입니다.

credits_charged
필수
number | null

필수

환불 로직 적용 후 차감된 크레딧입니다.

search_type
선택
string

선택

제품에서 반환하는 경우의 제품별 응답 유형.

오류
error
필수
string

필수

사람이 읽을 수 있는 오류 메시지입니다.

0
SUCCESS

요청이 성공했습니다. 제품별 결과 필드를 확인하세요. no_results만으로 HTTP 404를 입증하지 못합니다.

과금됨

1000
INVALID_REQUEST

본문 또는 매개변수가 없거나 잘못되었습니다.

과금 없음요청을 먼저 수정

1001
UNAUTHORIZED

API 키가 없거나 잘못되었거나 폐기되었습니다.

과금 없음요청을 먼저 수정

1004
NOT_FOUND

게이트웨이 라우팅 또는 카탈로그에 리소스가 없습니다.

과금 없음요청을 먼저 수정

1020
INSUFFICIENT_CREDITS

계정 잔액이 부족합니다.

과금 없음요청을 먼저 수정

1029
RATE_LIMITED

QPS 또는 동시 실행 한도를 초과했습니다.

과금 없음재시도 가능

1500
INTERNAL_ERROR

예기치 않은 내부 서버 오류.

과금 없음재시도 가능

1502
UPSTREAM_FAILED

워커가 원본 가져오기 또는 파싱 오류를 반환했습니다.

과금 없음재시도 가능

1503
SERVICE_UNAVAILABLE

사용 가능한 워커 세션이 없습니다.

과금 없음재시도 가능

1504
UPSTREAM_TIMEOUT

게이트웨이의 워커 결과 대기 시간이 초과되었습니다.

과금 없음재시도 가능

JSON
{
  "status": 1001,
  "error": "unauthorized",
  "request_id": "0f3576b2-6e2e-4f1e-bb0e-8cb0d4a60195",
  "elapsed_ms": 0,
  "credits_charged": 0
}
응답 헤더

모든 제품 응답에 이 헤더가 포함되어 메시지를 파싱하지 않고도 속도를 조절하고 재시도 여부를 판단할 수 있습니다.

X-RateLimit-Limit
계정에 허용된 초당 요청 수.
X-RateLimit-Remaining
현재 초에 남은 요청 수.
Retry-After
거부 시 다시 보내기 전에 기다릴 초.
X-SerpBase-Retryable
true면 같은 요청을 다시 보내 성공할 수 있고, false면 요청 자체를 바꿔야 합니다.
지원팀에 문의할 때
응답의 request_id(성공과 실패 모두 포함)와 호출 시각을 함께 보내 주세요. 그러면 해당 요청을 몇 초 만에 찾을 수 있습니다.
개인정보 및 보존
검색어는 과금, 디버깅, 남용 방지, 계정 로그를 위해 기록될 수 있습니다. 보존 정보는 개인정보 페이지를 확인하세요.

타임아웃

HTTP 클라이언트의 타임아웃을 60초로 설정하세요(문서의 코드 예시는 이미 그렇게 되어 있습니다). 모든 요청은 저희 쪽에서 30초 안에 결과나 오류로 끝나므로, 60초면 네트워크 여유까지 충분합니다.

  • 대부분의 요청은 몇 초 안에 응답하지만 15~20초 걸리는 경우도 있습니다. Google이 느리거나 인증을 요구하면 이 30초 안에 다른 경로로 다시 시도하기 때문입니다. 타임아웃이 짧으면 곧 성공할 요청을 끊게 됩니다.
  • 클라이언트가 먼저 포기하면 요청을 중단하고 환불하지만, 결과도 처리할 수 있는 오류도 받지 못합니다. 클라이언트 타임아웃을 30초 미만으로 설정하지 마세요.
  • 더 빨리 응답받아야 한다면 Google 검색 엔드포인트에 timeout 매개변수(1~30초)를 전달하세요. 예산에 맞춰 재시도가 더 일찍 시작되고, 예산이 다하면 즉시 status 1504를 받으며 과금되지 않습니다. HTTP 클라이언트의 타임아웃은 그보다 크게 두세요.
  • 그래도 실패하거나 시간이 초과되면 다시 보내세요. 성공한 시도만 과금됩니다.