Zerobus 수집 오류 처리

이 페이지에서는 Zerobus 수집 API에서 반환된 오류 코드와 클라이언트에서 이를 처리하는 방법을 설명합니다. 실패한 요청을 진단하거나 통합에서 오류 처리 논리를 구현할 때 이 참조를 사용합니다.

오류 응답 형식

오류 응답에는 머신에서 읽을 수 있는 오류 코드와 사용자가 읽을 수 있는 메시지가 포함되며 프로토콜에 적합한 형식으로 배달됩니다.

오류 응답은 적절한 HTTP 상태 코드가 있는 JSON으로 반환됩니다.

{
  "error_code": "NOT_FOUND",
  "message": "Table \"catalog.schema.table\" cannot be found."
}

분야	유형	설명
오류 코드	문자열	오류 범주를 식별하는 컴퓨터에서 읽을 수 있는 오류 코드입니다. 이를 사용하여 프로그래밍 방식으로 오류를 처리하는 방법을 결정합니다.
메시지	문자열	사람이 읽을 수 있는 오류 설명입니다. 문제 해결을 위한 추가 진단 정보가 포함될 수 있습니다. 이 필드를 프로그래밍 방식으로 구문 분석하지 마세요. 형식은 예고 없이 변경됩니다.

오류 응답은 응답 트레일러를 통해 전달되는 표준 gRPC 상태 코드를 사용합니다.

트레일러	설명
grpc-status	숫자 상태 코드(예: `3INVALID_ARGUMENT` 이를 사용하여 프로그래밍 방식으로 오류를 처리하는 방법을 결정합니다.
grpc 메시지	사람이 읽을 수 있는 오류 설명입니다. 문제 해결을 위한 추가 진단 정보가 포함될 수 있습니다. 이 필드를 프로그래밍 방식으로 구문 분석하지 마세요. 형식은 예고 없이 변경됩니다.

다음 섹션에서는 Zerobus 수집 API에서 반환된 오류 코드, 해당 프로토콜 수준 코드 및 권장되는 클라이언트 동작에 대해 설명합니다.

이러한 오류는 요청에 문제가 있음을 나타냅니다. 요청을 수정하지 않고 다시 시도하지 마세요.

오류 코드(REST)	gRPC 코드	HTTP 상태	설명	권장 작업
`INVALID_PARAMETER_VALUE`	`INVALID_ARGUMENT`(3)	400	요청에는 누락된 필수 필드, 잘못된 스키마 또는 지원되지 않는 레코드 형식과 같은 잘못되었거나 형식이 잘못된 입력이 포함됩니다.	요청을 수정하고 다시 제출합니다. `message` 필드를 검사하여 잘못된 매개 변수에 대한 세부 정보를 확인하세요.
`NOT_FOUND`	`NOT_FOUND`(5)	404	요청된 리소스가 없습니다. 예를 들어 지정된 테이블을 찾을 수 없습니다.	리소스 이름이 올바르고 존재하는지 확인합니다.
`NOT_IMPLEMENTED`	`UNIMPLEMENTED`(12)	501	요청된 작업은 지원되지 않습니다. 예를 들어 테이블은 지원되지 않는 기능 또는 데이터 형식을 사용합니다.	다시 시도하지 마세요. `message` 지원되지 않는 내용에 대한 자세한 내용은 필드를 확인합니다.

이러한 오류는 호출자의 ID 또는 사용 권한과 관련된 문제를 나타냅니다. 동일한 자격 증명으로 다시 시도하지 마세요.

오류 코드(REST)	gRPC 코드	HTTP 상태	설명	권장 작업
`UNAUTHENTICATED`	`UNAUTHENTICATED`(16)	401	요청에 유효한 인증 자격 증명이 없습니다. 토큰이 없거나, 비어 있거나, 만료되었거나, 유효하지 않을 수 있습니다.	유효한 인증 토큰을 새로 고치거나 제공하고 다시 시도합니다.
`PERMISSION_DENIED`	`PERMISSION_DENIED`(7)	403	호출자에게 지정된 리소스에 대해 요청된 작업을 수행할 수 있는 충분한 권한이 없습니다.	호출자에게 대상 리소스에 필요한 권한(예: `MODIFY`, , `SELECT`, `USE_CATALOGUSE_SCHEMA`)이 있는지 확인합니다.

이러한 오류는 서버 쪽에서 문제를 나타냅니다. 지수 백오프와 지터를 사용하여 재시도하십시오.

오류 코드(REST)	gRPC 코드	HTTP 상태	설명	권장 작업
`UNAVAILABLE`	`UNAVAILABLE`(14)	503	서비스가 일시적으로 요청을 처리할 수 없습니다. 이것은 일반적으로 일시적인 상태입니다.	지수 백오프와 지터를 사용하여 재시도하십시오.
`RESOURCE_EXHAUSTED`	`RESOURCE_EXHAUSTED`(8)	429	서비스가 리소스 제한으로 인해 요청을 거부합니다.	가능하면 요청 동시성을 줄입니다. 지수 백오프와 지터를 사용하여 재시도하십시오.
`INTERNAL_ERROR`	`INTERNAL`(13)	500	예기치 않은 내부 오류가 발생했습니다.	다시 시도하지 마세요. 지원에 문의하고 진단에 대한 전체 오류 응답을 제공합니다.

이 페이지가 도움이 되었나요?