Code

gRPC API의 표준 오류 코드입니다.

여러 오류 코드가 적용될 수 있는 경우도 있습니다. 서비스는 적용되는 오류 코드 중 가장 구체적인 코드를 반환해야 합니다. 예를 들어 두 코드가 모두 적용되는 경우 FAILED_PRECONDITION보다는 OUT_OF_RANGE를 사용하세요. 마찬가지로 FAILED_PRECONDITION보다는 NOT_FOUND 또는 ALREADY_EXISTS를 사용해야 합니다.

열거형
OK

오류가 아니며 성공 시 반환됩니다.

HTTP 매핑: 200 OK
CANCELLED

작업이 취소되었습니다. 대개 호출자에 의해 취소됩니다.

HTTP 매핑: 499 클라이언트에서 닫은 요청
UNKNOWN

알 수 없는 오류입니다. 예를 들어 다른 주소 공간에서 수신된 Status 값이 이 주소 공간에서 알려지지 않은 오류 공간에 속하는 경우 이 오류가 반환될 수 있습니다. 오류 정보를 충분히 반환하지 않는 API에서 발생한 오류가 이 오류로 변환될 수도 있습니다.

HTTP 매핑: 500 내부 서버 오류
INVALID_ARGUMENT

클라이언트에서 잘못된 인수를 지정했습니다. 이는 FAILED_PRECONDITION과 다릅니다. INVALID_ARGUMENT는 시스템 상태에 관계없이 문제가 있는 인수를 나타냅니다(예: 잘못된 형식의 파일 이름).

HTTP 매핑: 400 잘못된 요청
DEADLINE_EXCEEDED

작업을 완료하기 전에 기한이 지났습니다. 작업에서 시스템의 상태를 변경하는 경우 작업이 정상적으로 완료되었어도 이 오류가 반환될 수 있습니다. 예를 들어 서버의 성공 응답이 오래 지연되어 기한이 지났을 수 있습니다.

HTTP 매핑: 504 게이트웨이 시간 초과
NOT_FOUND

요청한 일부 항목(예: 파일 또는 디렉터리)을 찾을 수 없습니다.

서버 개발자 참고사항: 단계적 기능 출시, 잠정적 허용 목록 등으로 인해 전체 사용자 클래스에게 요청이 거부된 경우에는 NOT_FOUND를 사용할 수 있습니다. 사용자별 액세스 제어 등으로 인해 사용자 클래스에 속하는 일부 사용자에게 요청이 거부된 경우에는 PERMISSION_DENIED를 사용해야 합니다.

HTTP 매핑: 404 찾을 수 없음
ALREADY_EXISTS

클라이언트에서 만들려고 시도한 항목(예: 파일 또는 디렉토리)이 이미 존재합니다.

HTTP 매핑: 409 충돌
PERMISSION_DENIED

호출자에 지정한 작업을 실행할 권한이 없습니다. 일부 리소스가 소진되었기 때문에 거부된 경우에는 PERMISSION_DENIED가 아닌 RESOURCE_EXHAUSTED를 사용해야 합니다. 호출자를 식별할 수 없는 경우에는 PERMISSION_DENIED가 아닌 UNAUTHENTICATED를 사용해야 합니다. 이 오류 코드는 요청이 유효하다거나, 요청된 항목이 존재한다거나, 다른 전제조건이 충족되었음을 의미하지 않습니다.

HTTP 매핑: 403 금지됨
UNAUTHENTICATED

요청에 작업과 관련된 올바른 사용자 인증 정보가 없습니다.

HTTP 매핑: 401 승인되지 않음
RESOURCE_EXHAUSTED

일부 리소스가 소진되었습니다. 사용자당 할당량이나 전체 파일 시스템의 저장용량이 부족하기 때문일 수 있습니다.

HTTP 매핑: 429 요청한 횟수가 너무 많음
FAILED_PRECONDITION

시스템이 작업 실행에 필요한 상태가 아니기 때문에 작업이 거부되었습니다. 예를 들어 삭제할 디렉터리가 비어 있지 않거나, 디렉터리가 아닌 항목에 rmdir 작업을 적용한 경우입니다.

서비스 구현 시 다음과 같은 가이드라인에 따라 FAILED_PRECONDITION, ABORTED, UNAVAILABLE 중에서 결정할 수 있습니다. (a) 클라이언트에서 실패한 호출만 재시도할 수 있는 경우 UNAVAILABLE을 사용합니다. (b) 클라이언트가 상위 수준에서 다시 시도해야 하는 경우 ABORTED를 사용합니다. 예를 들어 클라이언트에서 지정한 테스트 및 설정이 실패하면 클라이언트가 읽기-수정-쓰기 시퀀스를 다시 시작해야 함을 나타냅니다. (c) 시스템 상태가 명시적으로 수정될 때까지 클라이언트에서 재시도하지 말아야 하는 경우 FAILED_PRECONDITION을 사용합니다. 예를 들어 디렉터리가 비어 있지 않아서 'rmdir'이 실패하면 파일이 디렉터리에서 삭제되지 않는 한, 클라이언트가 다시 시도해서는 안 되므로 FAILED_PRECONDITION가 반환되어야 합니다.

HTTP 매핑: 400 잘못된 요청
ABORTED

작업이 취소되었습니다. 대개 시퀀서 확인 실패, 트랜잭션 취소 등의 동시 실행 문제가 원인입니다.

FAILED_PRECONDITION, ABORTED, UNAVAILABLE 중에서 결정하는 방법은 위 가이드라인을 참조하세요.

HTTP 매핑: 409 충돌
OUT_OF_RANGE

유효한 범위를 벗어나는 작업을 시도했습니다. 예를 들어 파일 끝을 지나서 탐색하거나 읽으려고 했습니다.

INVALID_ARGUMENT와 달리, 이 오류는 시스템 상태가 변경되면 문제가 해결될 수 있음을 나타냅니다. 예를 들어 32비트 파일 시스템에서 [0,2^32-1] 범위를 벗어나는 오프셋으로 읽으려고 하면 INVALID_ARGUMENT가 발생하지만, 현재 파일 크기를 넘어서는 오프셋으로 읽으려고 하면 OUT_OF_RANGE가 발생합니다.

FAILED_PRECONDITION과 OUT_OF_RANGE 간에 다소 겹치는 부분이 있습니다. 적용할 때 더 구체적인 오류인 OUT_OF_RANGE를 사용하는 것이 좋습니다. 그러면 스페이스를 반복하는 호출자가 쉽게 OUT_OF_RANGE 오류를 찾아 완료 여부를 감지할 수 있습니다.

HTTP 매핑: 400 잘못된 요청
UNIMPLEMENTED

작업이 구현되지 않았거나 이 서비스에서 지원되지 않거나 사용 설정되지 않았습니다.

HTTP 매핑: 501 구현되지 않음
INTERNAL

내부 오류가 발생했습니다. 내부 시스템에서 예상하는 불변 항목에 문제가 있는 경우입니다. 이 오류 코드는 심각한 오류를 위해 예약되어 있습니다.

HTTP 매핑: 500 내부 서버 오류
UNAVAILABLE

현재 서비스를 사용할 수 없습니다. 일시적인 상태일 가능성이 높으며, 잠시 시간을 두고 다시 시도하면 해결될 수 있습니다. 멱등성이 없는 작업을 재시도하는 것이 항상 안전한 것은 아닙니다.

FAILED_PRECONDITION, ABORTED, UNAVAILABLE 중에서 결정하는 방법은 위 가이드라인을 참조하세요.

HTTP 매핑: 503 사용할 수 없는 서비스
DATA_LOSS

복구할 수 없는 데이터 손실이나 손상이 발생했습니다.

HTTP 매핑: 500 내부 서버 오류