BigQuery API의 HTTP 상태 및 오류 코드

이 페이지에서는 BigQuery API에서 반환하는 HTTP 상태 코드와 오류 메시지를 설명합니다. 이러한 코드를 사용하여 요청 실패를 해결하고 API 동작을 확인할 수 있습니다.

API가 아닌 오류, 클라이언트 라이브러리 연결 오류, Google Cloud 콘솔 오류에 대한 자세한 내용은 오류 메시지를 참조하세요.

쿼리 오류에 대한 자세한 내용은 쿼리 오류 문제 해결을 참고하세요.

스트리밍 삽입 오류에 대한 자세한 내용은 스트리밍 삽입 문제 해결을 참고하세요.

오류 응답 형식

BigQuery는 API에 표준 HTTP 오류 보고 형식을 사용합니다. 요청이 성공하면 2xx 범위의 HTTP 상태 코드가 반환됩니다. 실패한 요청은 4xx 및 5xx 범위의 상태 코드를 반환합니다. 리디렉션이 필요한 요청은 3xx 범위의 상태 코드를 반환합니다. 오류 응답에는 일반적으로 응답 본문에 JSON 문서가 포함되며, 여기에는 오류에 대한 정보가 포함된 오류 객체가 포함됩니다.

BigQuery API 응답에서 오류 객체는 일반적으로 다음 중 하나입니다.

이 페이지의 상태 코드 표에 있는 이유 열은 ErrorProto 객체의 reason 속성에 매핑됩니다. bq 명령줄 도구를 사용하여 작업 상태를 확인하는 경우 --format=prettyjson 플래그(예: bq --format=prettyjson show -j <var>JOB_ID</var>) 또는 --apilog=stdout를 사용하여 오류 객체와 해당 reason 속성을 확인합니다.

다음 표에서는 오류의 응답 본문에 표시될 수 있는 요소를 설명합니다. 문제를 파악하는 데 도움이 되도록 필드를 함께 사용해야 합니다. 또한 다음 표의 예시 값은 설명을 위한 것이며 가능한 모든 값의 전체 목록이 아닙니다.

요소 설명
code 텍스트 설명이 없는 HTTP 상태 코드 값입니다.

예시 값에는 400(잘못된 요청), 403(금지됨), 404(찾을 수 없음)가 포함됩니다.
error 오류 정보의 컨테이너입니다.
errors 오류 세부정보의 컨테이너입니다.
오류domain 오류의 범위입니다. 값 예시에는 global 및 usageLimits가 포함됩니다.
오류location 오류를 일으킨 locationType 내의 특정 항목입니다. 예를 들어 매개변수에 잘못된 값을 지정하면 location가 매개변수의 이름이 됩니다.

예시 값에는 Authorization 및 project가 포함됩니다.
오류locationType 오류를 일으킨 요청의 위치 또는 부분입니다. location와 함께 사용하여 오류를 정확히 파악합니다.

예시 값에는 header 및 parameter가 포함됩니다.
오류message 오류에 대한 설명입니다.

예시 값에는 Invalid argument, Access Denied, Not Found: Dataset myproject:foo가 있습니다.
오류reason 오류 원인의 고유 식별자입니다.

예시 값에는 invalid, accessDenied, notFound가 포함됩니다.
message 오류에 대한 설명입니다. errors.message와 동일합니다.

HTTP 상태 및 오류 코드

이 섹션에는 BigQuery API의 HTTP 상태 및 오류 코드의 일부 목록이 포함되어 있습니다. 1xx 정보 및 2xx 성공 코드는 생략됩니다. 자세한 내용은 RFC 7231 §6, RFC 7232 §4, RFC 7233 §4, RFC 7235 §3, RFC 6585의 응답 상태 코드를 참조하세요.

400 — 잘못된 요청

이유 HTTP 상태 코드 설명 문제 해결
badRequest 400

DML 문이 기존 tabledata.insertAll API로 최근에 스트리밍되었고 테이블의 스트리밍 버퍼에 남아 있는 행을 수정하려고 시도합니다. UPDATE or DELETE statement over table project.dataset.table would affect rows in the streaming buffer, which is not supported 오류가 반환됩니다.

BigQuery Storage Write API(gRPC)로 마이그레이션하고 스트리밍 버퍼가 플러시될 때까지 몇 분 정도 기다리거나 문을 필터링하여 최근에 스트리밍된 행을 제외합니다. 자세한 내용은 스트리밍 버퍼가 있는 테이블의 DML 문을 참조하세요.

invalid 400

요청에 잘못된 쿼리 외에 잘못된 입력이 포함되어 있습니다. 여기에는 다음 사례가 포함됩니다.

  • 스키마 불일치(Provided Schema does not match Table table)
  • 15단계 중첩 한도(Schema nested too deeply)를 초과하는 RECORD 열, 파일 또는 루틴
  • 작업 중에 삭제되거나 만료되는 대상 테이블(Destination deleted/expired during operation)

제공된 스키마가 기존 열 및 모드와 일치하는지 확인하고, 중첩 수준이 15개를 초과하는 구조를 평면화하거나 JSON로 저장하고, 대상 테이블 만료 시간을 실행 중인 작업보다 오래 지속되도록 설정합니다. 하위유형별 단계는 잘못된 입력 및 스키마 오류 문제 해결을 참조하세요.

invalidQuery 400

SQL 쿼리는 다음 이유 중 하나로 인해 검증 또는 실행 검사에 실패합니다.

  • SQL 문법, 식별자 또는 데이터 유형이 잘못되었습니다.
  • 충족되지 않은 기능 옵션 또는 필수 파티션 필터
  • 뷰 중첩 또는 파티션 출력 한도를 초과했습니다.
  • 동시 DML 트랜잭션 충돌(예: Concurrent conflicting update to details)

GoogleSQL 문법 또는 유형 불일치가 있는지 [line:column] 위치를 확인하고, 필수 OPTIONS 또는 파티션 필터를 충족하거나, 중단된 세션을 롤백하고 충돌하는 DML 작업을 다시 시도하세요. 자세한 내용은 잘못된 쿼리 오류 및 동시 업데이트로 인해 트랜잭션이 중단됨을 참조하세요.

jobBackendError 400

jobs.query 또는 jobs.getQueryResults에서 작업이 생성된 후 실행 중에 backendError로 실패했습니다. 오류는 The job encountered an error during execution. Retrying the job may solve the problem.를 반환합니다.

잘린 지수 백오프를 사용하여 새 jobId로 작업을 다시 시도하고 클라이언트 재시도 로직이 5xx 코드 외에 HTTP 400 응답을 처리하도록 합니다. 자세한 내용은 jobBackendError 및 jobInternalError 오류 문제 해결을 참조하세요.

jobInternalError 400

jobs.query 또는 jobs.getQueryResults에서 작업이 생성된 후 실행 중에 내부 오류로 인해 실패했습니다. 오류가 반환됩니다. The job encountered an internal error during execution and was unable to complete.

잘린 지수 백오프를 사용하여 새 jobId로 작업을 재시도합니다. 자세한 내용은 jobBackendError 및 jobInternalError 오류 문제 해결을 참조하세요.

preconditionFailed 400

다음과 같은 경우를 포함하여 요청 전제조건이 충족되지 않습니다.

  • 메타데이터 업데이트 중 If-Match ETag 불일치
  • 조직 정책에 필요한 CMEK 암호화 키가 누락되었습니다.
  • Standard 버전에서 지원되지 않는 기능
  • Enterprise Plus 기본 예약 외부의 장애 조치 데이터 세트에 쓰기
  • 업서트가 대기 중인 CDC 기본 테이블에 대한 구체화된 뷰 쿼리

다시 시도하기 전에 현재 리소스 etag를 가져오거나, 필요한 Cloud Key Management Service 키를 지정하거나, Enterprise 또는 Enterprise Plus 예약에서 워크로드를 실행하거나, 대기 중인 CDC 업서트가 적용될 때까지 몇 분 정도 기다리세요. 하위유형별 단계는 요청 전제조건 실패를 참조하세요.

resourceInUse 400

삭제 요청이 아직 활성 상태이거나 채워진 리소스를 타겟팅합니다.

  • 테이블, 뷰 또는 루틴이 여전히 포함된 데이터 세트
  • 아직 대기 중이거나 실행 중인 작업입니다.

resource_type resource_id is still in use 오류가 반환됩니다.

데이터 세트를 삭제하기 전에 비우거나(또는 deleteContents=true 설정, bq rm -r -f -d 실행, DROP SCHEMA IF EXISTS dataset_name CASCADE 실행) 작업 메타데이터를 삭제하기 전에 활성 작업이 완료될 때까지 기다리거나 취소합니다. 자세한 내용은 리소스가 아직 사용 중임을 참조하세요.

resourcesExceeded 400

작업이 다음 영역 중 하나에서 실행 리소스 한도를 초과합니다.

  • 테이블별 DML 동시 실행 큐 또는 세션 동시 실행 한도
  • 작업자, UDF, shuffle 또는 ML 모델 메모리 예산
  • 테이블 파티션(파티션 10,000개) 또는 출력 열 한도
  • Cloud Key Management Service CMEK 요청 비율, 스트리밍 읽기 또는 리전 간 데이터 전송
  • 쿼리 계획 복잡성 한도

Resources exceeded during query execution: details 오류가 반환됩니다.

쿼리를 간소화하거나, DML 작업을 일괄 처리하거나, 스캔된 열 또는 파티션을 줄이거나, 동일한 세션에서 동시 작업을 피하거나, 셔플이 많은 워크로드에 전용 슬롯 용량을 프로비저닝합니다. 하위 유형별 단계는 리소스 초과 문제 해결 및 쿼리가 메모리 리소스를 초과함을 참조하세요.

storageUnusable 400

서비스 측 스토리지 문제로 인해 테이블의 데이터를 보유하는 내부 BigQuery 스토리지를 일시적으로 사용할 수 없습니다. 오류가 반환됩니다. Storage of resource_id is unusable because reason.

잘린 지수 백오프를 사용하여 작업을 다시 시도합니다. 자세한 내용은 테이블 스토리지를 사용할 수 없음을 참조하세요.

streamingDataUnavailable 400

쓰기 최적화 스토리지에 최근에 스트리밍된 데이터는 읽기 작업에 일시적으로 사용할 수 없습니다. 오류가 반환됩니다. Job failed because streaming data from table_source is temporarily unavailable. Retrying the job may solve the problem.

잘린 지수 백오프를 사용하여 새 jobId로 작업을 다시 시도하고 클라이언트 재시도 로직이 HTTP 400 응답을 처리하는지 확인합니다. 자세한 내용은 스트리밍 데이터를 일시적으로 사용할 수 없음을 참조하세요.

tableUnavailable 400

BigQuery는 다음 경우를 포함하여 데이터를 관리하지 않는 테이블을 읽을 수 없습니다.

  • Apache Iceberg 또는 Delta Lake 테이블 스키마를 가져오는 중에 시간 초과가 발생합니다.
  • Hive 파티션을 나눈 외부 테이블에 파티션 키가 없습니다.
  • Google 관리 지원 테이블을 일시적으로 사용할 수 없습니다.

지수 백오프 자르기를 사용하여 스키마 가져오기 또는 백업 테이블 제한 시간 초과를 다시 시도하거나 key=value Cloud Storage URI 경로를 확인하고 하나 이상의 파티션 키를 사용하여 Hive 파티션을 나눈 외부 테이블을 다시 만듭니다. 자세한 내용은 외부 또는 지원 테이블을 사용할 수 없음을 참조하세요.

userOwnedResourceError 400

BigQuery에서 액세스할 때 소유한 외부 리소스가 오류를 반환합니다. Error when accessing a user-owned external resource_type resource resource_name. The resource provided error: external_error 오류가 반환됩니다.

오류 메시지에서 resource_type 및 resource_name를 검사하여 외부 리소스를 식별하고 external_error에 보고된 기본 오류를 해결합니다. 자세한 내용은 사용자 소유 외부 리소스 오류를 참조하세요.

vortexDataUnavailable 400

BigQuery Storage Write API(gRPC)를 사용하여 쓰기 최적화 스토리지로 최근에 스트리밍된 데이터는 일시적으로 쿼리에 사용할 수 없습니다. 오류가 반환됩니다. Job failed because vortex streaming data from table_source is temporarily unavailable. Retrying the job may solve the problem.

잘린 지수 백오프를 사용하여 새 jobId로 쿼리 작업을 다시 시도하고 클라이언트 재시도 로직이 HTTP 400 응답을 처리하는지 확인합니다. 자세한 내용은 스트리밍 데이터를 일시적으로 사용할 수 없음을 참조하세요.

billingTierLimitExceeded 400

주문형 쿼리가 스캔된 데이터 한도당 최대 CPU 사용량을 초과합니다. 오류가 반환됩니다. Query exceeded resource limits. This query used cpu_seconds_used CPU seconds but would charge only analysis_megabytes_billed M Analysis bytes... cpu_seconds_used CPU seconds were used, and this query must use less than cpu_seconds_limit CPU seconds.

SQL을 리팩터링하여 의도하지 않은 카티전 프로덕트, 부정확한 조인, 파티션을 나누지 않은 윈도우 함수 또는 과도한 JavaScript UDF를 삭제하거나 용량 기반(슬롯) 가격 책정으로 전환합니다. 자세한 내용은 쿼리가 CPU 리소스를 초과함 및 안티 SQL 패턴 방지를 참조하세요.

bytesBilledLimitExceeded 400

쿼리의 실행 전 상한 바이트 추정치가 실행 시작 전에 maximumBytesBilled를 초과합니다. 오류가 반환됩니다. Query exceeded limit for bytes billed: limit_bytes. required_bytes or higher required.

시험 이전으로 예상 바이트를 미리 보고, 필요한 열만 선택하고, 파티션을 나눈 열을 필터링하여 처리되는 데이터를 줄이거나 maximumBytesBilled를 required_bytes 이상으로 늘리세요. 자세한 내용은 쿼리가 최대 청구 바이트 한도를 초과함을 참조하세요.

jobRateLimitExceeded 400

jobs.query 또는 jobs.getQueryResults에서 다음 이유 중 하나로 인해 작업이 실패합니다.

  • 작업이 실행 중에 비율 제한을 초과합니다(Job exceeded rate limits: Your scope exceeded quota for quota_metric...).
  • 쿼리 큐 동시 실행 또는 연속 쿼리 슬롯 한도에 도달하여 쿼리가 허용되지 않습니다(예: Query was not admitted as the maximum concurrency has been reached...).

동시 제출을 줄이거나(또는 연속 쿼리에 일괄 우선순위 또는 슬롯 자동 확장을 사용) 잘린 지수 백오프를 사용하여 새 jobId로 작업을 다시 시도합니다. 자세한 내용은 작업이 비율 제한을 초과함 및 쿼리 승인이 거부됨을 참조하세요.

timeout 400

작업이 다음 사례를 포함하여 실행 시간 제한을 초과합니다.

  • 쿼리 또는 시험 이전이 6시간 실행 한도를 초과합니다.
  • 멀티 문 쿼리 내의 하위 작업이 타임아웃됩니다.
  • 외부 테이블 스키마 자동 감지가 타임아웃됩니다.

파티션을 나눈 열 또는 클러스터링된 열을 필터링하고 복잡한 쿼리 또는 다중 문 쿼리를 더 작은 단계로 분할하거나 외부 테이블을 만들 때 명시적 스키마와 더 좁은 소스 URI를 지정합니다. 자세한 내용은 쿼리가 실행 시간 제한을 초과함 및 할당량 및 한도 오류 문제 해결을 참조하세요.

invalidUser 400

예약된 쿼리가 잘못된 사용자 인증 정보로 구성되었습니다.

예약된 쿼리의 사용자 인증 정보를 새로고침합니다. 자세한 내용은 쿼리 예약을 참조하세요.

required 400

실행 전에 필수 입력이 누락되었습니다.

  • API 요청 페이로드 또는 URL의 필수 입력란이 제공되지 않았습니다.
  • 클라이언트 라이브러리의 필수 구성 객체가 비어 있거나 할당되지 않았습니다.

Required parameter is missing: parameter_name 오류가 반환됩니다.

BigQuery API 참조 또는 클라이언트 라이브러리 문서에서 필수 요청 본문과 쿼리 매개변수를 확인하고 API를 호출하기 전에 구성 객체를 검사합니다. 자세한 내용은 필수 매개변수 누락을 참조하세요.

401 — Unauthorized

다음은 요청에 유효한 사용자 인증 정보가 없는 경우 수신되는 오류 응답의 예시입니다.

401 Unauthorized

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "unauthenticated",
        "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential."
      }
    ],
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.",
    "status": "UNAUTHENTICATED"
  }
}
이유 HTTP 상태 코드 설명 문제 해결
unauthenticated 401

다음 이유 중 하나로 인해 요청 인증이 실패합니다.

  • 요청에 유효한 사용자 인증 정보가 없거나 만료된 OAuth 2.0 액세스 토큰을 사용합니다.
  • 최종 사용자 인증 정보 또는 서비스 계정 가장 권한이 누락되었습니다.
  • 호출자의 사용자 계정이 제한되거나 삭제되었습니다.

OAuth 또는 애플리케이션 기본 사용자 인증 정보를 새로고침하거나, 서비스 계정으로 실행하거나 가장할 때 roles/iam.serviceAccountUser 또는 roles/iam.serviceAccountTokenCreator을 부여하거나, 관리자에게 문의하여 제한된 계정을 복원하세요. 자세한 내용은 인증되지 않은 오류 문제 해결을 참조하세요.

403 — Forbidden

다음은 요청된 리소스에 액세스할 권한이 없는 경우 수신되는 오류 응답의 예시입니다.

403 Forbidden

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "accessDenied",
        "message": "Access Denied: Dataset myproject:mydataset: User does not have bigquery.datasets.get permission in project myproject."
      }
    ],
    "code": 403,
    "message": "Access Denied: Dataset myproject:mydataset: User does not have bigquery.datasets.get permission in project myproject."
  }
}
이유 HTTP 상태 코드 설명 문제 해결
responseTooLarge 403

쿼리 또는 테이블 읽기 응답이 다음 중 한 가지 방법으로 크기 한도를 초과합니다.

Response too large to return. details 오류가 반환됩니다.

대상 테이블을 지정하고(legacy SQL의 경우 configuration.query.allowLargeResults를 true로 설정) ORDER BY를 삭제하거나 LIMIT를 추가하거나 BigQuery Storage Read API 또는 EXPORT DATA를 사용하여 큰 행을 읽습니다. 자세한 내용은 쿼리 응답이 너무 큼 및 단일 행 응답 크기 한도 초과를 참조하세요.

apiLimitExceeded 403

요청이 다음 API 또는 메타데이터 한도 중 하나를 초과합니다.

  • 분당 API 요청 비율 제한
  • 테이블 또는 정책 메타데이터 평가 할당량
  • 리전 간 데이터 세트 복제본 생성 한도(Cannot add more than limit replicas for a region within window day(s))

API limit exceeded: details 오류가 반환됩니다.

잘린 지수 백오프, 일괄 로드 및 읽기로 실패한 요청을 다시 시도하고, 세분화된 테이블별 IAM 또는 행 수준 보안 정책을 간소화하고, 데이터 세트 복제본을 추가하기 전에 롤링 기간을 기다립니다. 자세한 내용은 API 비율 및 메타데이터 평가 한도 오류 및 리전 간 데이터 세트 복제본 생성 한도 오류를 참조하세요.

quotaExceeded 403

프로젝트가 다음 사용 할당량 중 하나를 초과합니다.

Quota exceeded: Your scope exceeded quota for quota_metric. For more information, see https://cloud.google.com/bigquery/docs/troubleshoot-quotas 오류가 반환됩니다.

message 오류를 검사하여 초과된 할당량을 확인하고, 고스캔 쿼리를 최적화하거나, 샌드박스에서 업그레이드하거나, 할당량 페이지에서 커스텀 할당량을 조정합니다. 자세한 내용은 커스텀 일일 쿼리 할당량 오류를 참조하세요.

rateLimitExceeded 403

다음 비율 또는 동시 실행 한도 중 하나로 인해 요청이 거부됩니다.

  • 단기 API 또는 쿼리 작업 비율 제한(Exceeded rate limits: too many quota_metric for this scope...)
  • 쿼리 큐 동시 실행 또는 연속 쿼리 예약 슬롯 한도(예: Query was not admitted as the maximum concurrency has been reached...)

요청 비율을 줄이고 잘린 지수 백오프를 사용하여 다시 시도하거나 일괄 우선순위로 긴급하지 않은 쿼리를 실행하고 예약 동시 실행 또는 슬롯 자동 확장을 조정합니다. 자세한 내용은 할당량 및 한도 오류 문제 해결 및 쿼리 승인 거부를 참조하세요.

accessDenied 403

다음 이유 중 하나로 인해 BigQuery 리소스에 대한 액세스가 거부됩니다.

  • 주 구성원에게 대상 프로젝트, 데이터 세트 또는 테이블에 필요한 IAM 권한이 없습니다.
  • 승인된 뷰, 행 수준 액세스 정책 또는 열 수준 정책 태그는 액세스를 제한합니다.
  • Cloud Key Management Service CMEK 권한 또는 외부 데이터 소스 권한이 누락되었습니다.

Access Denied: resource_type resource_id: details 오류가 반환됩니다.

Cloud 감사 로그(protoPayload.authorizationInfo) 및 정책 분석 도구를 검사하여 누락된 권한을 식별하고 최소 권한의 사전 정의된 BigQuery 역할을 부여합니다. 자세한 내용은 일반적인 액세스 거부 시나리오 문제 해결을 참조하세요.

policyViolation 403

보안 경계 또는 조직 정책이 요청을 차단합니다.

  • VPC 서비스 제어 경계는 액세스를 제한합니다(VPC-SC 프로젝트의 Google Drive 내보내기 또는 외부 테이블 포함).
  • constraints/gcp.resourceLocations과 같은 조직 정책 제약조건은 작업을 허용하지 않습니다.

vpcServiceControlsUniqueIdentifier로 로그 탐색기를 필터링하고 위반 분석기를 확인하거나, 경계 내에서 Cloud Storage 버킷을 사용하여 데이터를 내보내거나 로드하거나, 조직 정책 제약조건에서 허용하는 리전을 선택합니다. 자세한 내용은 정책 위반 오류 문제 해결을 참조하세요.

billingNotEnabled 403

요청된 작업에 대해 프로젝트에 활성 결제가 없습니다.

  • 프로젝트에 결제가 사용 설정되어 있지 않습니다.
  • 프로젝트는 BigQuery 샌드박스에서 실행되며, 테이블, 뷰, 파티션은 60일 후에 만료됩니다(expiration time must be less than 60 days).

Billing has not been enabled for this project. Enable billing at https://console.cloud.google.com/billing. details 오류가 반환됩니다.

Google Cloud 콘솔에서 프로젝트에 결제를 사용 설정하여 BigQuery 샌드박스에서 업그레이드한 다음 테이블, 뷰, 파티션의 기본 만료 시간을 업데이트합니다. 자세한 내용은 프로젝트에 결제가 사용 설정되지 않음을 참조하세요.

blocked 403

BigQuery에서 서비스 중단을 방지하기 위해 시도된 작업을 차단 목록에 일시적으로 추가했습니다. 오류가 반환됩니다. Request was blocked to protect the system's operation. Please contact support at https://cloud.google.com/support.

정확한 타임스탬프, 프로젝트 ID, BigQuery 작업 ID를 사용하여 Cloud Customer Care에 문의하여 관리 완화 규칙을 조사합니다. 자세한 내용은 시스템 작업을 보호하기 위해 요청이 차단됨을 참조하세요.

termsOfServiceNotAccepted 403

프로젝트에서 BigQuery 서비스 약관에 동의하지 않았습니다. BigQuery Terms of Service have not been accepted 오류가 반환됩니다.

Google Cloud 콘솔에 로그인하고, 메시지가 표시되면 시작 페이지에서 국가와 서비스 약관 체크박스를 선택하고 동의 및 계속을 클릭합니다. 자세한 내용은 BigQuery 서비스 약관에 동의하지 않음을 참조하세요.

404 — 찾을 수 없음

다음은 존재하지 않는 데이터 세트 또는 리소스를 검색하려고 할 때 수신되는 오류 응답의 예시입니다.

404 Not Found

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "Not Found: Dataset myproject:foo"
      }
    ],
    "code": 404,
    "message": "Not Found: Dataset myproject:foo"
  }
}
이유 HTTP 상태 코드 설명 문제 해결
notFound 404

다음 중 한 가지 이유로 요청된 리소스를 찾을 수 없습니다.

  • 대상 데이터 세트, 테이블 또는 작업이 존재하지 않거나 만료되었습니다.
  • 외부 Cloud Storage 또는 Google Drive 파일 URI가 없습니다.
  • 요청 위치가 데이터 세트 또는 작업 위치와 일치하지 않습니다.

Not found: resource_type resource_id 오류가 반환됩니다.

대소문자를 구분하는 정확한 프로젝트, 데이터 세트, 테이블 식별자 및 위치를 확인하고, 시간 이동 기간 내에 삭제된 테이블을 복원하고, 캐시된 결과 테이블이 만료된 쿼리를 다시 실행하거나, 외부 Cloud Storage 또는 Google Drive 파일이 있는지 확인합니다. 자세한 내용은 테이블을 찾을 수 없음, 위치를 찾을 수 없음, 작업을 찾을 수 없음을 참조하세요.

409 — 충돌

다음은 이미 존재하는 리소스를 만들려고 할 때 수신되는 오류 응답의 예시입니다.

409 Conflict

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "duplicate",
        "message": "Already Exists: Dataset myproject:mydataset"
      }
    ],
    "code": 409,
    "message": "Already Exists: Dataset myproject:mydataset"
  }
}
이유 HTTP 상태 코드 설명 문제 해결
abortd 409

동시 수정 또는 충돌로 인해 작업이 중지됩니다(abortd 이유와 함께 반환됨).

잘린 지수 백오프를 사용하여 충돌하는 작업이 완료된 후 작업을 다시 시도하거나 중지된 다중 문 트랜잭션을 롤백한 후 다시 시도합니다. 자세한 내용은 작업이 중단됨을 참조하세요.

duplicate 409

요청이 다음 방법 중 하나로 기존 리소스와 충돌합니다.

  • 이미 존재하는 데이터 세트, 테이블 또는 작업 리소스를 만듭니다.
  • 대상 테이블이 이미 있는 경우 writeDisposition를 WRITE_EMPTY로 설정하여 작업을 실행합니다.

Already Exists: resource_type resource_id 오류가 반환됩니다.

다른 리소스 이름을 사용하거나, DDL 문에서 IF NOT EXISTS 또는 CREATE OR REPLACE를 사용하거나, writeDisposition를 WRITE_APPEND 또는 WRITE_TRUNCATE로 변경하거나, BigQuery에서 임의의 jobId를 생성하도록 하세요. 하위유형별 단계는 리소스가 이미 있음을 참조하세요.

499 — 클라이언트가 요청을 종료함

이유 HTTP 상태 코드 설명 문제 해결
stopped 499

다음 이유 중 하나로 인해 작업이 완료되기 전에 중지됩니다(jobs.get 폴링은 reason: stopped와 함께 HTTP 200를 반환함).

  • 호출자가 작업을 명시적으로 취소합니다(User requested cancellation).
  • 작업이 구성된 실행 또는 큐 제한 시간(Job timed out after duration 또는 Job timed out in the queue after duration)을 초과합니다.

Job execution was cancelled: details 오류가 반환됩니다.

configuration.jobTimeoutMs 또는 프로젝트 큐 제한 시간 옵션을 늘리거나(또는 쿼리 런타임 및 동시 실행 최적화) Cloud 감사 로그에서 jobservice.cancel 호출을 확인합니다. 하위유형별 단계는 작업 실행이 취소됨을 참조하세요.

500 — 내부 서버 오류

이유 HTTP 상태 코드 설명 문제 해결
internalError 500

BigQuery 내에서 내부 오류가 발생했습니다. 오류가 반환됩니다. An internal error occurred and the request could not be completed.

BigQuery 서비스수준계약의 백오프 요구사항에 따라 기다린 후 지수 백오프 자르기를 사용하여 다시 시도하거나 예약을 사용하여 일시적인 오류 빈도를 줄입니다. 자세한 내용은 internalError 오류 문제 해결을 참조하세요.

501 — 구현되지 않음

이유 HTTP 상태 코드 설명 문제 해결
notImplemented 501

요청이 다음과 같이 대상 리소스에 대해 구현되지 않은 기능이나 작업을 사용하려고 시도합니다.

  • 관리되지 않는 스토리지 유형이 있는 테이블 복사
  • 지원되지 않는 ALTER SEARCH INDEX 옵션을 실행합니다.

Not Implemented: details 오류가 반환됩니다.

CREATE TABLE destination_table AS SELECT * FROM source_table를 사용하여 지원되지 않는 테이블 복사 소스를 구체화하거나 DROP SEARCH INDEX 및 CREATE SEARCH INDEX를 사용하여 검색 색인을 삭제하고 다시 만듭니다. 하위 유형별 단계는 기능 또는 작업이 구현되지 않음을 참고하세요.

503 — 서비스를 사용할 수 없음

이유 HTTP 상태 코드 설명 문제 해결
backendError 503

다음 중 한 가지 이유로 인해 서비스를 일시적으로 사용할 수 없습니다.

  • 서비스 수요 급증(로드 셰딩) 또는 내부 리소스 소진
  • 간헐적인 네트워크 연결 문제
  • 일시적인 백엔드 구성요소 문제입니다.

오류가 반환됩니다. Error encountered during execution. Retrying may solve the problem.

잘린 지수 백오프를 사용하여 요청을 다시 시도하고 새 jobId로 실패한 작업을 다시 시도합니다. 재시도 후에도 오류가 계속되면 30일 실패율을 BigQuery SLA와 비교하고 Cloud Customer Care에 문의하세요. backendError 오류 문제 해결을 참조하세요.