API 오류

이 페이지는 GenerateContent API가 반환하는 백엔드 오류 코드 참조, gRPC 오류 응답 형식 설명, 그리고 문제 해결 절차를 제공해요.

출처: 원문

본문

HTTP 오류 코드

다음 표는 일반적인 백엔드 오류 코드와 원인 설명, 권장 해결 방법을 보여줘요.

HTTP 코드	상태	설명	예시	해결 방법
400	INVALID_ARGUMENT	요청 본문이 잘못됐어요.	요청에 오타가 있거나 필수 필드가 빠졌어요.	API 참조에서 요청 형식·예시·지원 버전을 확인하세요. 더 새 API 버전의 기능을 옛 엔드포인트에서 쓰면 오류가 날 수 있어요.
400	FAILED_PRECONDITION	Gemini API 무료 등급을 해당 국가에서 지원하지 않아요. Google AI Studio에서 프로젝트에 결제를 활성화해 주세요.	무료 등급이 지원되지 않는 지역에서 요청하는데 Google AI Studio에서 결제를 활성화하지 않았어요.	Gemini API를 쓰려면 Google AI Studio에서 유료 플랜을 설정해야 해요.
402	RESOURCE_EXHAUSTED	Prepay 크레딧 잔액이 소진됐어요.	결제 계정의 Prepay 크레딧이 모두 소진돼 그 결제 계정에 연결된 모든 API 키가 작동을 멈춰요.	결제 계정에 크레딧 추가 또는 자동 충전을 켜세요. 크레딧이 추가되기 전까지 성공하지 않으므로 이 요청을 재시도하지 마세요.
403	PERMISSION_DENIED	API 키에 필요한 권한이 없어요.	잘못된 API 키를 쓰거나 적절한 인증 없이 튜닝된 모델을 쓰려고 해요.	API 키가 설정됐고 올바른 접근 권한이 있는지 확인하세요. 튜닝된 모델을 쓰려면 적절한 인증을 거치세요.
404	NOT_FOUND	요청한 리소스를 찾을 수 없어요.	요청에서 참조한 이미지·오디오·비디오 파일을 찾을 수 없어요.	요청의 모든 파라미터가 API 버전에 유효한지 확인하세요.
429	RESOURCE_EXHAUSTED	API의 속도 제한(RPM, TPM, RPD, 지출 등) 중 하나를 초과했어요.	요청을 너무 많이 보내거나 토큰을 너무 많이 쓰거나 계정 결제 기록·등급에 따른 지출 한도를 초과했어요.	모델의 속도 제한 안에 있는지 확인하세요. 잠시 기다렸다가 재시도하세요. 요청 속도나 크기를 줄이세요. 필요하면 속도 제한 증가 요청을 하세요.
499	CANCELLED	보통 호출자에 의해 작업이 취소됐어요.	API가 응답을 끝내기 전에 클라이언트가 연결을 닫았어요.	클라이언트나 네트워크 인프라가 연결을 조기에 닫는지(예: 클라이언트 측 타임아웃) 확인하세요.
500	INTERNAL	Google 측에서 예상치 못한 오류가 발생했어요.	입력 컨텍스트가 너무 길어요.	Gemini API 상태 페이지에서 진행 중인 사고를 확인하세요. 입력 컨텍스트를 줄이거나 다른 모델(예: Gemini 2.5 Pro → Gemini 2.5 Flash)로 일시 전환해 보세요. 잠시 기다렸다가 재시도하세요. 재시도해도 지속되면 Google AI Studio의 Send feedback 버튼으로 보고하세요.
503	UNAVAILABLE	서비스가 일시적으로 과부하되거나 다운됐을 수 있어요.	서비스가 일시적으로 용량이 부족해요.	Gemini API 상태 페이지에서 진행 중인 사고를 확인하세요. 다른 모델(예: Gemini 2.5 Pro → Gemini 2.5 Flash)로 일시 전환해 보세요. 잠시 기다렸다가 재시도하세요. 재시도해도 지속되면 Send feedback 버튼으로 보고하세요.
504	DEADLINE_EXCEEDED	서비스가 마감 시간 안에 처리를 끝내지 못했어요.	프롬프트(또는 컨텍스트)가 제시간에 처리하기엔 너무 커요.	클라이언트 요청에서 'timeout'을 더 크게 설정해 이 오류를 피하세요.

오류 응답 형식

GenerateContent 요청이 실패하면 API는 HTTP 상태 코드(예: 400 Bad Request, 403 Forbidden, 429 Too Many Requests)를 설정하고 gRPC 상태 상세를 담은 JSON 응답 본문을 반환해요.

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}

필드	타입	설명
`code`	integer	HTTP 상태 코드.
`message`	string	사람이 읽을 수 있는 오류 설명.
`status`	string	`SCREAMING_CASE` 형식의 gRPC 상태 코드.
`details`	array	`ErrorInfo`나 `LocalizedMessage` 같은 추가 오류 컨텍스트.

다음 단계

API 문제 해결: 일반적인 문제와 오류 시나리오 해결.
속도 제한: 요청 제한과 할당량 처리 학습.

API 오류

API 오류

본문

HTTP 오류 코드

오류 응답 형식

다음 단계

더 알아보기 (Learn more)