이 페이지에서는 BigQuery API에서 반환하는 HTTP 상태 코드와 오류 메시지를 설명합니다. 이러한 코드를 사용하여 요청 실패를 해결하고 API 동작을 확인할 수 있습니다.
API가 아닌 오류, 클라이언트 라이브러리 연결 오류, Google Cloud 콘솔 오류에 대한 자세한 내용은 오류 메시지를 참조하세요.
쿼리 오류에 대한 자세한 내용은 쿼리 오류 문제 해결을 참고하세요.
스트리밍 삽입 오류에 대한 자세한 내용은 스트리밍 삽입 문제 해결을 참고하세요.
오류 응답 형식
BigQuery는 API에 표준 HTTP 오류 보고 형식을 사용합니다. 요청이 성공하면 2xx 범위의 HTTP 상태 코드가 반환됩니다. 실패한 요청은 4xx 및 5xx 범위의 상태 코드를 반환합니다. 리디렉션이 필요한 요청은 3xx 범위의 상태 코드를 반환합니다. 오류 응답에는 일반적으로 응답 본문에 JSON 문서가 포함되며, 여기에는 오류에 대한 정보가 포함된 오류 객체가 포함됩니다.
BigQuery API 응답에서 오류 객체는 일반적으로 다음 중 하나입니다.
ErrorProto객체의 배열을 포함하는errors객체- 단일
ErrorProto객체를 포함하는errorResults객체
이 페이지의 상태 코드 표에 있는 이유 열은 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 문이 기존 |
BigQuery Storage Write API(gRPC)로 마이그레이션하고 스트리밍 버퍼가 플러시될 때까지 몇 분 정도 기다리거나 문을 필터링하여 최근에 스트리밍된 행을 제외합니다. 자세한 내용은 스트리밍 버퍼가 있는 테이블의 DML 문을 참조하세요. |
invalid |
400 |
요청에 잘못된 쿼리 외에 잘못된 입력이 포함되어 있습니다. 여기에는 다음 사례가 포함됩니다.
|
제공된 스키마가 기존 열 및 모드와 일치하는지 확인하고, 중첩 수준이 15개를 초과하는 구조를 평면화하거나 |
invalidQuery |
400 |
SQL 쿼리는 다음 이유 중 하나로 인해 검증 또는 실행 검사에 실패합니다.
|
GoogleSQL 문법 또는 유형 불일치가 있는지 |
jobBackendError |
400 |
|
잘린 지수 백오프를 사용하여 새 |
jobInternalError |
400 |
|
잘린 지수 백오프를 사용하여 새 |
preconditionFailed |
400 |
다음과 같은 경우를 포함하여 요청 전제조건이 충족되지 않습니다.
|
다시 시도하기 전에 현재 리소스 |
resourceInUse |
400 |
삭제 요청이 아직 활성 상태이거나 채워진 리소스를 타겟팅합니다.
|
데이터 세트를 삭제하기 전에 비우거나(또는 |
resourcesExceeded |
400 |
작업이 다음 영역 중 하나에서 실행 리소스 한도를 초과합니다.
|
쿼리를 간소화하거나, DML 작업을 일괄 처리하거나, 스캔된 열 또는 파티션을 줄이거나, 동일한 세션에서 동시 작업을 피하거나, 셔플이 많은 워크로드에 전용 슬롯 용량을 프로비저닝합니다. 하위 유형별 단계는 리소스 초과 문제 해결 및 쿼리가 메모리 리소스를 초과함을 참조하세요. |
storageUnusable |
400 |
서비스 측 스토리지 문제로 인해 테이블의 데이터를 보유하는 내부 BigQuery 스토리지를 일시적으로 사용할 수 없습니다. 오류가 반환됩니다.
|
잘린 지수 백오프를 사용하여 작업을 다시 시도합니다. 자세한 내용은 테이블 스토리지를 사용할 수 없음을 참조하세요. |
streamingDataUnavailable |
400 |
쓰기 최적화 스토리지에 최근에 스트리밍된 데이터는 읽기 작업에 일시적으로 사용할 수 없습니다. 오류가 반환됩니다. |
잘린 지수 백오프를 사용하여 새 |
tableUnavailable |
400 |
BigQuery는 다음 경우를 포함하여 데이터를 관리하지 않는 테이블을 읽을 수 없습니다.
|
지수 백오프 자르기를 사용하여 스키마 가져오기 또는 백업 테이블 제한 시간 초과를 다시 시도하거나 |
userOwnedResourceError |
400 |
BigQuery에서 액세스할 때 소유한 외부 리소스가 오류를 반환합니다. |
오류 메시지에서 resource_type 및 resource_name를 검사하여 외부 리소스를 식별하고 external_error에 보고된 기본 오류를 해결합니다. 자세한 내용은 사용자 소유 외부 리소스 오류를 참조하세요. |
vortexDataUnavailable |
400 |
BigQuery Storage Write API(gRPC)를 사용하여 쓰기 최적화 스토리지로 최근에 스트리밍된 데이터는 일시적으로 쿼리에 사용할 수 없습니다. 오류가 반환됩니다. |
잘린 지수 백오프를 사용하여 새 |
billingTierLimitExceeded |
400 |
주문형 쿼리가 스캔된 데이터 한도당 최대 CPU 사용량을 초과합니다. 오류가 반환됩니다. |
SQL을 리팩터링하여 의도하지 않은 카티전 프로덕트, 부정확한 조인, 파티션을 나누지 않은 윈도우 함수 또는 과도한 JavaScript UDF를 삭제하거나 용량 기반(슬롯) 가격 책정으로 전환합니다. 자세한 내용은 쿼리가 CPU 리소스를 초과함 및 안티 SQL 패턴 방지를 참조하세요. |
bytesBilledLimitExceeded |
400 |
쿼리의 실행 전 상한 바이트 추정치가 실행 시작 전에 |
시험 이전으로 예상 바이트를 미리 보고, 필요한 열만 선택하고, 파티션을 나눈 열을 필터링하여 처리되는 데이터를 줄이거나 |
jobRateLimitExceeded |
400 |
|
동시 제출을 줄이거나(또는 연속 쿼리에 일괄 우선순위 또는 슬롯 자동 확장을 사용) 잘린 지수 백오프를 사용하여 새 |
timeout |
400 |
작업이 다음 사례를 포함하여 실행 시간 제한을 초과합니다.
|
파티션을 나눈 열 또는 클러스터링된 열을 필터링하고 복잡한 쿼리 또는 다중 문 쿼리를 더 작은 단계로 분할하거나 외부 테이블을 만들 때 명시적 스키마와 더 좁은 소스 URI를 지정합니다. 자세한 내용은 쿼리가 실행 시간 제한을 초과함 및 할당량 및 한도 오류 문제 해결을 참조하세요. |
invalidUser |
400 |
예약된 쿼리가 잘못된 사용자 인증 정보로 구성되었습니다. |
예약된 쿼리의 사용자 인증 정보를 새로고침합니다. 자세한 내용은 쿼리 예약을 참조하세요. |
required |
400 |
실행 전에 필수 입력이 누락되었습니다.
|
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 또는 애플리케이션 기본 사용자 인증 정보를 새로고침하거나, 서비스 계정으로 실행하거나 가장할 때 |
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 |
쿼리 또는 테이블 읽기 응답이 다음 중 한 가지 방법으로 크기 한도를 초과합니다.
|
대상 테이블을 지정하고(legacy SQL의 경우 |
apiLimitExceeded |
403 |
요청이 다음 API 또는 메타데이터 한도 중 하나를 초과합니다.
|
잘린 지수 백오프, 일괄 로드 및 읽기로 실패한 요청을 다시 시도하고, 세분화된 테이블별 IAM 또는 행 수준 보안 정책을 간소화하고, 데이터 세트 복제본을 추가하기 전에 롤링 기간을 기다립니다. 자세한 내용은 API 비율 및 메타데이터 평가 한도 오류 및 리전 간 데이터 세트 복제본 생성 한도 오류를 참조하세요. |
quotaExceeded |
403 |
프로젝트가 다음 사용 할당량 중 하나를 초과합니다.
|
|
rateLimitExceeded |
403 |
다음 비율 또는 동시 실행 한도 중 하나로 인해 요청이 거부됩니다.
|
요청 비율을 줄이고 잘린 지수 백오프를 사용하여 다시 시도하거나 일괄 우선순위로 긴급하지 않은 쿼리를 실행하고 예약 동시 실행 또는 슬롯 자동 확장을 조정합니다. 자세한 내용은 할당량 및 한도 오류 문제 해결 및 쿼리 승인 거부를 참조하세요. |
accessDenied |
403 |
다음 이유 중 하나로 인해 BigQuery 리소스에 대한 액세스가 거부됩니다.
|
Cloud 감사 로그( |
policyViolation |
403 |
보안 경계 또는 조직 정책이 요청을 차단합니다.
|
|
billingNotEnabled |
403 |
요청된 작업에 대해 프로젝트에 활성 결제가 없습니다.
|
Google Cloud 콘솔에서 프로젝트에 결제를 사용 설정하여 BigQuery 샌드박스에서 업그레이드한 다음 테이블, 뷰, 파티션의 기본 만료 시간을 업데이트합니다. 자세한 내용은 프로젝트에 결제가 사용 설정되지 않음을 참조하세요. |
blocked |
403 |
BigQuery에서 서비스 중단을 방지하기 위해 시도된 작업을 차단 목록에 일시적으로 추가했습니다. 오류가 반환됩니다. |
정확한 타임스탬프, 프로젝트 ID, BigQuery 작업 ID를 사용하여 Cloud Customer Care에 문의하여 관리 완화 규칙을 조사합니다. 자세한 내용은 시스템 작업을 보호하기 위해 요청이 차단됨을 참조하세요. |
termsOfServiceNotAccepted |
403 |
프로젝트에서 BigQuery 서비스 약관에 동의하지 않았습니다. |
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 파일이 있는지 확인합니다. 자세한 내용은 테이블을 찾을 수 없음, 위치를 찾을 수 없음, 작업을 찾을 수 없음을 참조하세요. |
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 |
동시 수정 또는 충돌로 인해 작업이 중지됩니다( |
잘린 지수 백오프를 사용하여 충돌하는 작업이 완료된 후 작업을 다시 시도하거나 중지된 다중 문 트랜잭션을 롤백한 후 다시 시도합니다. 자세한 내용은 작업이 중단됨을 참조하세요. |
duplicate |
409 |
요청이 다음 방법 중 하나로 기존 리소스와 충돌합니다.
|
다른 리소스 이름을 사용하거나, DDL 문에서 |
499 — 클라이언트가 요청을 종료함
| 이유 | HTTP 상태 코드 | 설명 | 문제 해결 |
|---|---|---|---|
stopped |
499 |
다음 이유 중 하나로 인해 작업이 완료되기 전에 중지됩니다(
|
|
500 — 내부 서버 오류
| 이유 | HTTP 상태 코드 | 설명 | 문제 해결 |
|---|---|---|---|
internalError |
500 |
BigQuery 내에서 내부 오류가 발생했습니다. 오류가 반환됩니다.
|
BigQuery 서비스수준계약의 백오프 요구사항에 따라 기다린 후 지수 백오프 자르기를 사용하여 다시 시도하거나 예약을 사용하여 일시적인 오류 빈도를 줄입니다. 자세한 내용은 internalError 오류 문제 해결을 참조하세요. |
501 — 구현되지 않음
| 이유 | HTTP 상태 코드 | 설명 | 문제 해결 |
|---|---|---|---|
notImplemented |
501 |
요청이 다음과 같이 대상 리소스에 대해 구현되지 않은 기능이나 작업을 사용하려고 시도합니다.
|
|
503 — 서비스를 사용할 수 없음
| 이유 | HTTP 상태 코드 | 설명 | 문제 해결 |
|---|---|---|---|
backendError |
503 |
다음 중 한 가지 이유로 인해 서비스를 일시적으로 사용할 수 없습니다.
오류가 반환됩니다. |
잘린 지수 백오프를 사용하여 요청을 다시 시도하고 새 |