여러 오류 코드가 적용될 수 있는 경우도 있습니다. 서비스는 적용되는 오류 코드 중 가장 구체적인 코드를 반환해야 합니다. 예를 들어 두 코드가 모두 적용되는 경우 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 내부 서버 오류
상태
Status 유형은 REST API, RPC API를 비롯하여 다양한 프로그래밍 환경에 적합한 논리적 오류 모델을 정의하며, gRPC에서 사용됩니다. 각 Status 메시지에는 오류 코드, 오류 메시지, 오류 세부정보라는 3가지 데이터가 포함됩니다.
API 설계 가이드에서 이 오류 모델과 모델 작업 방법에 대해 자세히 알아볼 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-31(UTC)"],[[["\u003cp\u003eThe document outlines the \u003ccode\u003eCode\u003c/code\u003e enum, which defines canonical error codes for gRPC APIs, recommending the most specific code be used when multiple codes apply.\u003c/p\u003e\n"],["\u003cp\u003eThere are various \u003ccode\u003eCode\u003c/code\u003e enum values detailed in the content, such as \u003ccode\u003eOK\u003c/code\u003e, \u003ccode\u003eCANCELLED\u003c/code\u003e, \u003ccode\u003eUNKNOWN\u003c/code\u003e, \u003ccode\u003eINVALID_ARGUMENT\u003c/code\u003e, \u003ccode\u003eNOT_FOUND\u003c/code\u003e, and more, each with a corresponding HTTP mapping and a specific context in which it should be used.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eStatus\u003c/code\u003e message type, suitable for REST and RPC APIs, is described, and it includes the fields \u003ccode\u003ecode\u003c/code\u003e (an enum value from \u003ccode\u003egoogle.rpc.Code\u003c/code\u003e), \u003ccode\u003emessage\u003c/code\u003e (a developer-facing error message), and \u003ccode\u003edetails[]\u003c/code\u003e (a list of error detail messages).\u003c/p\u003e\n"],["\u003cp\u003eThe document explains when to choose between similar error codes, such as the difference between \u003ccode\u003eFAILED_PRECONDITION\u003c/code\u003e, \u003ccode\u003eABORTED\u003c/code\u003e, and \u003ccode\u003eUNAVAILABLE\u003c/code\u003e or the distinction between \u003ccode\u003eINVALID_ARGUMENT\u003c/code\u003e and \u003ccode\u003eOUT_OF_RANGE\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# Package google.rpc\n\nIndex\n-----\n\n- [Code](/distributed-cloud/hosted/docs/latest/gdch/apis/vertex-ai/translation/rpc/google.rpc#google.rpc.Code) (enum)\n- [Status](/distributed-cloud/hosted/docs/latest/gdch/apis/vertex-ai/translation/rpc/google.rpc#google.rpc.Status) (message)\n\nCode\n----\n\nThe canonical error codes for gRPC APIs.\n\nSometimes multiple error codes might apply. Services should return the most specific error code that applies. For example, prefer `OUT_OF_RANGE` over `FAILED_PRECONDITION` if both codes apply. Similarly prefer `NOT_FOUND` or `ALREADY_EXISTS` over `FAILED_PRECONDITION`.\n\nStatus\n------\n\nThe `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details.\n\nYou can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors)."]]
