Gemini 4 API 오류 진단: Carbon·Neon·Hydrogen 요청이 실패하는 원인과 해결

상태 코드와 응답 구조로 Gemini 4 Carbon·Neon·Hydrogen API 오류를 진단합니다. 잘못된 모델 ID, 무료 등급 제한, 429, 사고 수준, 빈 응답, 도구 호출, 안전 차단을 다룹니다.

문이 열린 차단기 분전반 선화. 두 줄로 늘어선 스위치 가운데 주황색 하나만 내려가 있다.

Gemini 4 API 오류는 대부분 다섯 가지로 나뉩니다. 모델 ID나 경로 오류, 프로젝트 등급(Carbon과 Neon은 유료 등급 전용), 할당량(429), 지원되지 않는 파라미터(minimal, 또는 Carbon의 xhigh), 그리고 사고가 max_output_tokens를 모두 써 버려 형식상 성공했지만 답이 없는 응답입니다. HTTP 상태, 오류 code, 응답 구조를 보고 어느 경우인지 판단하세요. 새 API 키로 해결되는 경우는 키가 유출되었거나 차단된 좁은 경우 하나뿐입니다.

이 글은 Gemini 4 Carbon, Neon, Hydrogen을 다룹니다. Argon은 Gemini 4 Argon API 오류 해결이라는 별도 가이드가 있으며, 그 글의 장애 기록 템플릿과 합성 테스트 사례는 여기서 반복하지 않습니다. 아래 Google 관련 사실은 Gemini API 문서를 바탕으로 2026년 11월 19일에 확인했습니다(본문의 Google 문서 링크는 모두 영어 페이지입니다). Ofox 결과는 같은 날 Ofox를 통해 google/gemini-4-hydrogen과 google/gemini-4-argon에 보낸 실제 요청 21건에서 나왔으며, 사례마다 한 번씩 실행했습니다(총비용 추정 0.05달러 미만). Carbon과 Neon은 Ofox에서 사용할 수 없으므로(2026년 11월 19일 카탈로그 확인), Carbon과 Neon 예제는 모두 Google 네이티브 API를 사용합니다.

이 글은 Ofox가 발행합니다. 게이트웨이 결과가 Google 문서와 다를 때는 둘 다 제시하며, 그 차이를 Google 자체 엔드포인트의 규칙으로 제시하지 않습니다.

증상부터 진단하기

위에서부터 처음으로 맞는 행을 사용하세요. 각 행은 해결 방법과 확인 단계가 있는 섹션으로 연결됩니다.

보이는 현상가장 가능성 높은 원인먼저 확인할 것섹션
404 model_not_found오타, 임의로 붙인 접미사, 또는 현재 경로가 제공하지 않는 모델제공업체의 최신 모델 목록에서 ID 복사모델 ID
인증, 무료 등급, 결제를 언급하는 403 PERMISSION_DENIED프로젝트 등급 또는 결제 상태키가 아니라 AI Studio의 프로젝트 상태유료 등급
402 payment_required선불 크레딧 소진결제 잔액. 재시도하지 않음유료 등급
rate_limit_exceeded / too_many_requests가 있는 429분당 순간 트래픽 급증동시 실행 수와 토큰 속도429
quota_exceeded가 있는 429일일 할당량 소진초기화를 기다림. 재시도해도 소용없음429
thinking_level을 언급하는 400해당 모델에서 유효하지 않은 수준모델별 수준 표사고 수준
Gemini 3.x에서 이전한 뒤 발생한 400예전 샘플링, 캐싱, 도구 프롬프트 설정마이그레이션 체크리스트마이그레이션
HTTP 200, 빈 텍스트, MAX_TOKENS / length / incomplete사고가 출력 예산을 다 씀max_output_tokens와 thinking_level출력 예산
상태가 requires_continuation포그라운드 한 번의 호출이 상한에 도달SDK 버전 또는 이어서 보내는 루프출력 예산
백그라운드 작업이 failed이거나 멈춤서버 측 실패, 24시간 제한, 또는 store=falseinteraction 상태와 errors 목록백그라운드
missing_thought_signature, malformed_function_call도구 호출 기록이 바뀌었거나 도구를 선언하지 않음기록을 다시 보내는 방식도구 호출
code가 safety, prohibited_content인 400콘텐츠 필터프롬프트와 안전 설정안전

메시지보다 오류 구조를 먼저 보기

Google과 Ofox 같은 게이트웨이는 오류 형식이 다릅니다. 텍스트를 보고 조치하기 전에 어느 쪽이 응답했는지 확인하세요.

Google의 Interactions API는 Google의 API 오류 참조에 따라 기계가 읽을 수 있는 code와 message를 담은 error 객체를 반환합니다.

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. ..."
  }
}

스트리밍에서는 같은 객체가 "event_type": "error"가 붙은 SSE 이벤트로 도착합니다. 스트림이 HTTP 200으로 시작한 뒤에 실패할 수도 있으므로, 스트림을 읽는 코드는 error 이벤트를 처리해야 합니다. 기존 generateContent API는 예전 Google RPC 방식을 사용해 INVALID_ARGUMENT, RESOURCE_EXHAUSTED 같은 상태 이름을 씁니다. Google 문제 해결 페이지에 두 가지 이름이 함께 나오는 이유입니다.

Ofox 게이트웨이는 테스트에서 두 가지 구조를 반환했습니다. 모델 ID가 게이트웨이 카탈로그에 없으면 게이트웨이가 자체 오류 본문으로 응답했습니다(요청 ID는 줄였습니다). 메시지 형식은 Ofox Gemini 가이드의 모델 ID 오타 행과 같습니다.

{"error": {"message": "Model 'google/gemini-4-carbon' not found",
           "type": "model_not_found", "code": 404, "request_id": "e0925435-..."}}

요청이 Google 쪽에 도달한 뒤(Ofox는 Ofox Gemini 가이드에 따르면 Vertex AI를 통해 Gemini를 제공합니다) 거기서 거부되면, 상위 서비스의 텍스트가 게이트웨이 형식에 감싸여 돌아왔습니다.

{"error": {"code": null,
  "message": "Invalid value at 'generation_config.thinking_config.thinking_level' (type.googleapis.com/google.cloud.aiplatform.v1.GenerationConfig.ThinkingConfig.ThinkingLevel),",
  "param": null, "request_id": "1439e1a1-...", "type": "INVALID_ARGUMENT"}}

메시지에 google.cloud.aiplatform 타입 이름이 있으면 상위 모델 서비스가 그 값을 거부했다는 뜻입니다. Model '<id>' not found 메시지는 게이트웨이가 모델 ID를 인식하지 못했다는 뜻입니다.

Ofox의 오류 처리 가이드는 상태 코드와 재시도 가능 여부를 설명합니다. 그 가이드의 오류 본문 예시는 "code": "invalid_api_key"와 "type": "authentication_error"이고, 표에는 404의 type이 not_found_error로 나와 있습니다. 2026년 11월 19일에 실제로 받은 본문은 구조가 달랐습니다. 401은 "code": 401과 "type": "invalid_api_key", 404는 "code": 404와 "type": "model_not_found"였습니다. 처리 코드가 이 필드로 분기한다면 code와 type을 모두 확인하고, 직접 사용하는 경로에서 받은 실제 오류로 테스트하세요.

404 model not found: ID나 경로가 잘못됨

증상. Google: code가 model_not_found인 404. Ofox: type이 model_not_found이고 메시지가 Model '<id>' not found인 404.

원인. Google API에서 Gemini 4 모델 ID 네 개는 정확히 gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen, gemini-4-argon입니다(모델 페이지). 어느 것에도 -preview나 -latest 접미사가 없습니다. 또 다른 흔한 원인은 해당 모델을 아예 제공하지 않는 경로를 쓰는 경우입니다.

2026년 11월 19일 Ofox를 통해 보낸 요청(각 1회 실행):

보낸 모델 문자열엔드포인트결과
google/gemini-4-hydrogen-preview/v1/chat/completions404 model_not_found
google/gemini-4-hydrogen-preview/gemini/v1beta/models/...:generateContent404 model_not_found
google/gemini-4-carbon/v1/chat/completions404 model_not_found
google/gemini-4-neon/v1/chat/completions404 model_not_found
gemini-4-hydrogen(google/ 접두사 없음)/v1/chat/completions200, 응답의 model 필드는 google/gemini-4-hydrogen

해결. Google에서는 접두사 없는 ID를 사용합니다. Ofox에서는 google/gemini-4-hydrogen 또는 google/gemini-4-argon을 사용합니다. 접두사 없는 형태도 테스트에서 인식되었고, Ofox Gemini 가이드에도 접두사는 선택 사항이라고 나와 있습니다. Carbon이나 Neon은 Google 유료 등급 프로젝트를 사용하세요. 철자를 바꾼다고 게이트웨이 목록에 없는 모델이 나타나지는 않습니다.

확인. 앱이 쓰는 것과 같은 엔드포인트와 키로 모델 목록을 조회합니다. Google에서는 GET https://generativelanguage.googleapis.com/v1beta/models, Ofox에서는 GET https://api.ofox.io/v1/models입니다. Google은 models.list가 키의 존재 여부만 확인한다고 안내합니다. 목록 엔드포인트가 200을 반환해도 그 프로젝트에서 추론이 활성화되었다는 증거는 아니므로, 작은 생성 요청을 한 번 보내 확인하세요.

무료 등급 프로젝트에서 Carbon과 Neon이 실패할 때

증상. Hydrogen에서는 되는 요청이 모델을 Carbon이나 Neon으로 바꾸면 실패합니다. 흔한 신호는 403 PERMISSION_DENIED, AI Studio 프로젝트 상태 Free tier unavailable 또는 Payment needed, 한 번도 결제를 설정하지 않은 프로젝트의 할당량 오류입니다.

원인. Carbon 가이드는 Carbon이 “is not available on the Free tier”(무료 등급에서는 사용할 수 없음)라고 밝힙니다. Neon 가이드는 Neon이 “available on the paid tier only”(유료 등급에서만 사용 가능)라고 합니다. 무료 등급이 있는 Gemini 4 모델은 Hydrogen뿐입니다(요금). 무료 등급 프로젝트가 Carbon이나 Neon을 호출할 때의 모델별 오류 문자열은 Google이 공개하지 않으므로, 정확한 텍스트로 일치 여부를 판단하지 마세요. 상태로 판단한 다음 프로젝트를 확인하세요.

Google의 문제 해결 가이드는 프로젝트 수준의 403 변형을 다음과 같이 정리합니다.

신호의미해결
FREE_TIER_VERIFICATION_REQUIRED가 있는 403, 상태 Verification needed무료 등급 프로젝트에 인증이 필요함모바일 기기로 인증하거나 결제를 설정
상태 Free tier unavailable프로젝트가 무료 등급 대상이 아님활성 Cloud Billing 계정 연결
상태 Payment needed, 또는 미납 잔액을 언급하는 403결제 계정 연체잔액을 정산하면 접근이 자동으로 복구됨
키가 유출된 것으로 신고되었다는 403Google이 키를 차단함새 키를 만들고 클라이언트 코드에 넣지 않기
402 payment_required선불 크레딧 소진크레딧을 추가하거나 자동 충전을 켜기. 재시도하지 않음

자주 놓치는 점이 두 가지 있습니다. 사용 자격은 Google Cloud 프로젝트 단위로 확인되므로, 같은 프로젝트의 다른 키를 써도 결과가 같습니다. 또 유료 등급으로 업그레이드한다고 무료 등급 할당량이 열리지는 않으며, 유료 사용량은 과금됩니다. 무료 등급에서 한도 0으로 표시되는 429라면 Gemini 무료 등급 한도 0 진단(영문)에서 할당량 지표를 읽는 방법을 확인하세요. 이미지 모델을 다룬 글이지만 프로젝트 확인 방법은 같습니다. Hydrogen 무료 등급에 무엇이 포함되는지는 Gemini 4 무료 API 등급 가이드를 참고하세요.

확인. AI Studio에서 키를 소유한 프로젝트를 열어 등급을 확인합니다. 그다음 짧은 Carbon 또는 Neon 요청을 한 번 보냅니다. Carbon과 Argon 가격은 2026년 12월 1일에 두 배가 됩니다(Carbon 가이드). 구체적인 숫자는 12월 가격 변경 분석에 있습니다.

429: 순간 급증과 할당량 소진 구분하기

증상. HTTP 429. Interactions API에서는 code가 rate_limit_exceeded, too_many_requests, quota_exceeded 중 하나입니다. generateContent에서는 RESOURCE_EXHAUSTED입니다.

원인. Google의 속도 제한 페이지는 세 가지를 정하고 있습니다.

  • 제한은 API 키가 아니라 프로젝트 단위로 적용됩니다.
  • 일일 요청 할당량은 태평양 시간 자정에 초기화됩니다.
  • 유료 프로젝트에는 10분 단위 이동 창으로 계산하는 지출 기반 한도도 있습니다. Tier 1은 10달러, Tier 2와 Tier 3은 200달러입니다. 이를 넘으면 요청 속도가 낮아도 429 RESOURCE_EXHAUSTED가 반환됩니다.

Gemini 4에서는 지출 한도를 놓치기 쉽습니다. Neon과 Hydrogen은 기본으로 high 사고를 사용하고, 사고 토큰은 출력 토큰으로 과금됩니다. 길고 사고량이 많은 요청 몇 건만으로도 RPM 한도를 하나도 넘지 않은 채 Tier 1 지출 창에 도달할 수 있습니다.

해결. code에 맞춰 조치하세요.

Code할 일하지 말 것
rate_limit_exceeded, too_many_requests지터를 넣은 지수 백오프, 동시 실행 수 낮추기병렬로 즉시 재시도
quota_exceeded초기화될 때까지 작업을 멈추거나 할당량 증가 요청일일 할당량에 재시도 예산 낭비
지출 기반 RESOURCE_EXHAUSTED비싼 호출을 시간상 분산, thinking_level이나 출력 크기 낮추기RPM 한도라고 단정

Google의 Python SDK는 이미 429와 5xx를 최대 네 번 재시도하며, 약 1초에서 시작해 최대 60초까지 늘립니다(문제 해결). 여기에 자체 재시도 루프를 덧씌우면 한 번의 실패가 열 건이 넘는 요청으로 불어날 수 있습니다. 재시도는 한 계층에만 맡기세요. 일반적인 429 재시도 가이드(영문)는 헤더와 백오프 시점을, AI API 오류 처리(영문)는 백오프와 서킷 브레이커 코드를 다룹니다.

Ofox에서는. 게이트웨이의 429(오류 처리 가이드에서 type은 rate_limit_error)는 Google 프로젝트 할당량과는 별개의 한도입니다. Ofox 속도 제한 문서에는 기본값이 100 RPM이며 팀의 모든 키를 합산한다고 나와 있습니다(2026년 11월 19일 재확인). 더 높은 한도가 필요하면 그 페이지 안내대로 Ofox에 이메일로 요청할 수 있습니다. 테스트에서는 429가 발생하지 않았습니다.

확인. 429가 날 때마다 정확한 code를 기록하세요. 백오프를 넣은 뒤에도 quota_exceeded가 계속 나온다면 문제는 트래픽 형태가 아니라 할당량입니다.

사고 수준 오류: minimal과 xhigh

Gemini 4 모델이 모두 같은 사고 수준을 지원하지는 않습니다. Google의 사고 가이드는 다음과 같이 정리합니다.

모델기본값지원 수준
gemini-4-carbonmediumlow, medium, high
gemini-4-argonmediumlow, medium, high
gemini-4-neonhighlow, medium, high, xhigh
gemini-4-hydrogenhighlow, medium, high, xhigh

minimal은 어떤 Gemini 4 모델에서도 지원되지 않습니다. Neon과 Hydrogen 마이그레이션 체크리스트에는 두 모델 모두 minimal을 오류로 거부한다고 나와 있습니다. Google 사고 가이드는 gemini-3.8-flash에서도 minimal을 미지원으로 표시하므로, 이를 받아들이던 예전 모델에서 복사한 설정도 똑같이 바꿔야 합니다. Google은 Carbon과 Argon의 상한이 high라고 하지만, 이 모델들에서 xhigh를 쓸 때의 정확한 오류 메시지는 공개하지 않았습니다.

해결. 예전 설정을 명시적으로 바꾸세요. minimal은 low로, Carbon과 Argon에서는 xhigh를 high로 바꿉니다. 보내기 전에 자체 코드에서 모델 ID에 맞는 수준인지 검증하세요.

게이트웨이가 실제로 한 일. Ofox 테스트를 보면 서버가 이 문제를 잡아 줄 것이라고 기대하면 안 되는 이유를 알 수 있습니다.

요청(Ofox, 2026-11-19, 각 1회 실행)결과
Hydrogen, Chat Completions reasoning_effort: "minimal"200, 오류 없음, 추론 토큰 20개
Hydrogen, 네이티브 thinkingLevel: "minimal"200, 오류 없음, 사고 토큰 22개
Argon, Chat Completions reasoning_effort: "xhigh"200, 오류 없음, 추론 토큰 157개
Argon, 네이티브 thinkingLevel: "xhigh"200, 오류 없음, 사고 토큰 131개
Hydrogen, reasoning_effort: "banana"400 INVALID_ARGUMENT(위 예시)

Google이 유효하지 않다고 문서화한 값이 오류 없이 받아들여졌지만, 그렇다고 그 값이 효과를 냈다는 뜻은 아닙니다. 어떤 수준이 적용되었는지 보여 주는 정보는 응답 어디에도 없습니다. 게이트웨이가 값을 버렸을 수도 있고, 지원되는 수준으로 바꿨을 수도 있습니다. 같은 프롬프트에서 사고 설정 없이 실행한 Hydrogen은 사고 토큰을 22~82개 사용했고, minimal 두 번은 각각 20개와 22개를 썼으므로 한 번씩 실행한 토큰 수로는 무슨 일이 있었는지 알 수 없습니다. Argon은 기준 실행을 아예 하지 않았습니다. 임의로 만든 값은 상위 서비스에서 거부되었습니다. 이것은 하루, 한 경로에서 얻은 단일 관찰로 다루세요. 이 동작에 의존하지 마세요. 게이트웨이가 받아 줬다는 이유로 minimal을 보내는 코드는 Google을 직접 호출할 때 깨질 수 있습니다. Ofox Gemini 사고 가이드에 thinkingLevel과 reasoning_effort 필드 설명이 있습니다. 작업에 맞는 수준 선택은 Gemini 4 사고 수준을 참고하세요.

답이 비었거나 잘릴 때: 함께 쓰는 1M 창

증상. HTTP 200인데 텍스트가 비었거나 중간에 잘립니다. 네이티브 generateContent는 finishReason: "MAX_TOKENS", Chat Completions는 finish_reason: "length", Interactions 리소스는 상태 incomplete를 보여 줍니다.

원인. Gemini 4에서 max_output_tokens는 사고와 화면에 보이는 출력을 합친 양을 제한합니다. Google의 긴 출력 가이드가 바로 이 증상을 설명합니다. 상태가 incomplete이고 텍스트가 비어 있으면 “the model used all tokens on thinking.”(모델이 모든 토큰을 사고에 썼다)라는 뜻입니다. 예전 앱에서 가져온 8,192 같은 상한은 이런 상황을 훨씬 쉽게 만들며, 기본값이 high인 Neon과 Hydrogen에서 특히 그렇습니다.

한 줄짜리 산수 문제로 Ofox를 통한 Hydrogen에서 이를 재현했습니다.

경로설정결과
Chat Completionsmax_tokens: 16200, content: "", finish_reason: "length", completion 토큰 16개 중 13개가 추론
네이티브 generateContentmaxOutputTokens: 16200, parts가 없는 candidate, finishReason: "MAX_TOKENS", thoughtsTokenCount: 13

요청은 실패하지 않았고 과금도 되었습니다. 답만 없습니다. 앱이 HTTP 상태만 확인한다면 답이 빈 성공 응답을 그대로 보여 주게 됩니다.

해결.

  • 낮게 하드코딩한 상한을 없애세요. Google은 Carbon에 최소 32,768을 권장합니다. Neon과 Hydrogen은 기본값 65,536을 유지하거나 필드를 생략하세요.
  • 토큰을 덜 쓰려면 thinking_level을 낮추세요. Google 긴 출력 가이드에 따르면 max_output_tokens를 낮춘다고 모델이 더 간결하게 사고하지는 않으며, 응답이 더 일찍 잘릴 뿐입니다.
  • 64K 토큰을 넘는 출력이 필요하면 background: true를 설정하고 max_output_tokens를 65,536보다 크게, 최대 1,048,576에서 입력 토큰 수를 뺀 값까지 설정하세요.

공유 창의 한도. 입력, 사고, 출력은 1,048,576토큰짜리 창 하나를 함께 씁니다. Google에서는 입력과 max_output_tokens의 합이 창을 넘으면 API가 요청을 거부하지 않고 출력 한도를 남은 공간만큼으로 줄입니다(사고 가이드). Ofox에서 max_tokens: 2000000(Chat Completions)과 maxOutputTokens: 2000000(네이티브)으로 보낸 요청은 둘 다 오류 없이 받아들여졌고 정상적으로 답했습니다. 다만 실제로 어떤 상한이 적용되었는지는 응답에 나타나지 않습니다. 입력만으로 창을 넘으면 즉시 오류가 납니다. Ofox Gemini 가이드에는 400 INVALID_ARGUMENT와 The input token count exceeds the maximum number of tokens allowed 1048576. 메시지가 나와 있습니다. 100만 토큰짜리 테스트 입력은 테스트 예산을 넘기 때문에 이 경우는 재현하지 않았습니다.

호출당 상한. 포그라운드 한 번의 호출(hop)은 Neon과 Hydrogen에서 65,536토큰이 상한이지만, Carbon과 Argon의 비스트리밍 호출에서는 32,768입니다. 예산이 남았는데 한 번의 호출이 상한에 도달하면 상태가 requires_continuation이 됩니다. Python 2.34.0, JavaScript 2.32.0, Go 1.77.0, Java 1.80.0, .NET 1.28.0보다 오래된 SDK는 포그라운드 interaction을 자동으로 이어 가지 않습니다. SDK를 업그레이드하거나 previous_interaction_id와 continuation_token을 붙여 다음 호출을 보내세요.

확인. 응답을 검사할 때는 HTTP 상태만이 아니라 종료 신호(status == "completed", finishReason == "STOP", 또는 finish_reason == "stop")와 텍스트가 비어 있지 않은지를 모두 확인하세요.

백그라운드 실행과 오래 걸리는 interaction

오래 걸리는 Carbon과 Neon 작업은 백그라운드 실행으로 보내야 합니다. Google의 백그라운드 실행 가이드와 긴 출력 가이드는 다음 실패를 문서화합니다.

증상원인해결
생성 시 400background: true와 store: false를 함께 설정백그라운드 작업에는 store: true(기본값) 유지
다음 턴을 이어 붙일 때 400이전 interaction이 아직 in_progresscompleted가 된 뒤에 그 ID를 previous_interaction_id로 전달
상태 failed실행 중 오류(Google 예시: 도구 실패, 속도 제한) 또는 작업이 24시간을 넘김한 번 재시도하고, 또 실패하면 interaction ID를 지원팀에 전달
errors에 안전 관련 code가 있는 상태 failed작업 중 콘텐츠가 차단됨안전 섹션 참고. 같은 입력으로 재시도해도 소용없음
클라이언트 타임아웃, 작업 상태 불명HTTP 타임아웃이 추론 시간보다 짧음다시 제출하기 전에 저장한 interaction ID를 폴링
GET에서 404interaction이 삭제됨삭제하기 전에 결과를 가져오기

Google은 Carbon과 Neon에서 어려운 프롬프트를 다룰 때 HTTP 타임아웃을 최소 15분으로 하거나 백그라운드 실행을 쓰라고 권장합니다. 취소되거나 실패한 interaction은 멈추기 전까지 처리한 작업만큼 과금됩니다. 따라서 타임아웃 뒤 다시 제출하는 클라이언트는 같은 작업에 두 번 비용을 낼 수 있습니다. 작업을 만들자마자 interaction ID를 저장하세요.

도구 호출 오류: 사고 서명과 잘못된 형식의 호출

Google API 오류 페이지는 생성 오류 코드로 malformed_function_call, malformed_tool_call, unexpected_tool_call, too_many_tool_calls, missing_thought_signature를 나열합니다.

마이그레이션 뒤의 MALFORMED_FUNCTION_CALL. Neon과 Hydrogen 가이드는 도구를 선언하지 않은 상태에서 시스템 지시로 모델이 원시 텍스트 JSON 형태의 도구 호출을 내보내게 하지 말라고 경고합니다. 그러면 MALFORMED_FUNCTION_CALL이 반환될 수 있기 때문입니다. API의 function calling 필드로 도구를 선언하거나, JSON에는 구조화된 출력을 사용해 해결하세요.

missing_thought_signature. 사고 서명(thought signature)은 턴 사이에 모델의 추론 상태를 전달합니다. Google의 규칙은 다음과 같습니다.

  • Interactions API에서 store: true와 previous_interaction_id를 쓰면 서명은 서버가 처리합니다. 따로 할 일이 없습니다.
  • 상태를 저장하지 않는 모드에서는 모든 thought 블록을 받은 그대로 다시 보내세요. 모델을 바꾼 뒤 이전 모델의 블록, 내장 도구 호출 블록과 결과 블록에 붙은 서명도 포함됩니다.
  • 클라이언트가 관리하는 generateContent 기록에서는 이전 모델 턴과 서명을 바꾸지 않고 돌려보내며, 서명 하나를 병렬 functionCall 파트에 복사하지 마세요.

Ofox를 통해 서명이 없는 functionCall 파트가 들어 있는 네이티브 generateContent 기록을 Hydrogen에 보냈습니다. 요청은 오류 없이 받아들여졌고 도구 결과를 바탕으로 답했습니다. 한 경로에서 한 번 실행한 결과로는 서명 검사가 실행되었는지, 기록이 다른 방식으로 처리되었는지 알 수 없으므로, 서명을 빼도 된다는 뜻으로 받아들이지 마세요. Google 마이그레이션 체크리스트는 서명을 바꾸지 말고 그대로 돌려보내라고 합니다. REST, SDK, 호환 어댑터 전반의 필드별 수정은 missing thought_signature 해결 가이드를 참고하세요. 테스트에서 Ofox의 Chat Completions 응답은 서명을 message.reasoning_details(type reasoning.encrypted)에 담았습니다. 프레임워크가 assistant 턴을 다시 보낸다면 이 객체를 보존하세요.

안전 차단과 인용(recitation) 차단

증상. Google의 안전 설정 가이드는 차단된 입력이나 응답이 “fails with an HTTP 400 error”(HTTP 400 오류로 실패)하며 차단된 콘텐츠는 반환되지 않는다고 설명합니다. 문서의 예시는 다음과 같습니다.

{"error": {"code": "safety",
  "message": "Request blocked due to safety violations (harmful content). Please modify your input and retry."}}

입력 차단에는 jailbreak, prohibited_content, blocklist code가 쓰이며 메시지는 Input blocked:로 시작합니다. Google API 오류 페이지에는 recitation, language, spii, content_blocked 등 생성 차단을 나타내는 다른 code도 있습니다. 백그라운드 모드에서는 interaction 상태가 failed가 되고 code가 errors 목록에 나타납니다. 스트리밍에서는 error 이벤트로 도착합니다.

해결. 이런 오류는 장애가 아니라 콘텐츠 문제로 다루고, 자동으로 재시도하지 마세요. 조정 가능한 안전 필터는 Gemini 2.5 이후 모델에서 기본값이 Off이고, 일부 유해 유형은 설정과 관계없이 항상 차단되므로 임곗값을 낮춰도 모든 차단이 풀리지는 않습니다. 정당한 요청을 다시 작성하세요. 필터를 우회하려 하지 마세요. BlockedReason.OTHER는 요청이 약관을 위반하거나 지원되지 않을 수 있다는 뜻입니다. RECITATION에 대해 Google은 프롬프트와 컨텍스트를 더 고유하게 만들라고 제안합니다. temperature에 관한 예전 조언은 temperature를 무시하는 Gemini 4에는 해당하지 않습니다.

확인. code를 요청 ID와 함께 기록해 모니터링에서 콘텐츠 차단과 5xx 장애를 구분할 수 있게 하세요.

마이그레이션과 지원 중단 관련 오류

업그레이드 직후 보이는 400은 대부분 Gemini 3.x에서 작동하던 설정에서 나옵니다. Google의 마이그레이션 체크리스트 세 개에서 Carbon, Neon, Hydrogen의 문서화된 호환성 파괴 변경을 정리했습니다.

예전 설정Gemini 4 동작해결
temperature, top_p, top_k무시되며 지원 중단 경고 헤더가 붙음(문제 해결). 범위를 벗어난 값은 400 반환(Neon·Hydrogen 가이드). Google은 향후 릴리스에서 400을 반환할 것이라고 함세 가지 모두 제거
cached_content, caches.create명시적 캐싱 미지원제거. 4,096토큰 이상 프롬프트에는 암시적 캐싱이 적용됨
thinking_level: "minimal"Neon과 Hydrogen에서 거부됨low 사용
max_output_tokens: 8192사고가 상한의 대부분을 소비32,768~65,536으로 상향
1보다 큰 candidate_countGemini 3과 4에서 미지원제거

샘플링 파라미터의 경우, Ofox를 통해 Hydrogen에 temperature: 5를 보낸 요청은 Chat Completions와 네이티브 경로 모두에서 오류 없이 받아들여졌습니다(HTTP 200). 확보한 전체 응답 헤더에 지원 중단 경고 헤더가 없었으므로, 그 값이 Google까지 전달되었는지조차 응답으로는 알 수 없습니다. Google Hydrogen 가이드는 범위를 벗어난 값이 400을 반환한다고 합니다. 같은 코드가 어느 경로에서든 같게 동작하도록 이 파라미터를 제거하세요.

지원 중단된 모델 ID. Google 지원 중단 페이지에는 2026년 11월 19일 기준으로 어떤 Gemini 4 모델에도 종료일이 없습니다. 예상 밖의 일은 예전 ID에서 생깁니다. gemini-3.7-flash와 gemini-3.5-flash는 이미 더 새로운 Flash 모델로 자동 라우팅됩니다. 2026년 12월 1일부터는 모든 gemini-2.5-pro API 요청이 gemini-3.8-flash로 라우팅되고 3.8 Flash 요금으로 과금됩니다. 라우팅 변경은 오류가 아니지만, 알려 주는 오류 없이 모델 동작과 비용을 바꿉니다. 소리 없이 경로가 바뀐 것을 알아챌 수 있도록 modelVersion 필드(Ofox는 model 또는 modelVersion으로 반환)를 고정하고 기록하세요. 3.8 Flash에서 옮겨 간다면 Gemini 3.8 Flash에서 Hydrogen으로 마이그레이션 가이드에 이전 전후 테스트 계획이 있습니다.

어떤 오류를 재시도할까

백오프 후 재시도요청을 고치고 재시도하지 않음용량이나 결제 복구를 기다림
429 속도 제한 / too many requests, 500, 503, 504, 408, 상태 failed(1회)모든 400, 401, 403, 404, 안전 및 생성 차단 code429 quota_exceeded, 402 payment_required, 지출 기반 RESOURCE_EXHAUSTED

이는 400, 402, 403을 재시도하지 말라는 Google의 안내와도, 400, 401, 402, 403, 404는 재시도 불가이고 429, 500, 502, 503은 재시도 가능하다는 Ofox 표와도 일치합니다. 제공업체별 상태 코드 비교는 LLM API 오류 코드 참조(영문)를 보세요.

테스트한 것과 하지 않은 것

2026년 11월 19일 Ofox를 통해 사례마다 한 번씩 테스트했습니다(temperature 사례만 전체 헤더를 확보하려고 두 번 더 실행). 대상은 잘못된 ID, 목록에 없는 모델, 접두사 없는 ID, 요청 다섯 건에 걸친 세 가지 사고 수준 값(minimal, xhigh, 유효하지 않은 값), 아주 큰 출력 상한과 아주 작은 출력 상한, 범위를 벗어난 temperature, 서명 없는 도구 기록, 유효하지 않은 키(401, type invalid_api_key, 메시지 Invalid or expired API key)입니다. 프롬프트는 아주 단순했습니다(“Reply with the single word OK”와 한 줄짜리 산수 문제). 원본 요청과 응답은 키를 가린 채 저장했습니다.

테스트하지 않은 것: Google 엔드포인트에서의 Carbon·Neon 호출, 무료 등급 403, 실제 429, 안전 차단, 백그라운드 작업, 컨텍스트 초과. 이 섹션들은 Google 문서에 근거하며, 메시지는 Google이나 Ofox가 명시한 경우에만 인용했습니다. 테스트에서 200은 요청이 거부되지 않았다는 뜻일 뿐입니다. 게이트웨이 동작은 예고 없이 바뀔 수 있으니, 파라미터 사례는 직접 사용하는 경로에서 다시 확인하세요.

아직 연결을 준비하는 중이라면 Hydrogen API 설정 가이드, Carbon API 설정 가이드, Neon API 가이드 중 하나로 시작하고, 요청이 실패하면 이 글로 돌아오세요.

관련 문서

자주 묻는 질문

Gemini 4 요청은 성공했는데 텍스트가 비어 있는 이유는 무엇인가요?
사고와 화면에 보이는 출력은 max_output_tokens를 함께 씁니다. 상한이 낮으면 모델이 예산 전체를 사고에 써 버릴 수 있습니다. Ofox를 통한 테스트에서 Hydrogen에 max_tokens를 16으로 설정하자 HTTP 200과 함께 빈 content, finish_reason "length"가 반환되었습니다. 상한을 올리거나(Google은 Carbon에 최소 32,768, Neon과 Hydrogen에는 기본값 65,536을 권장합니다) thinking_level을 낮추세요.
Ofox로 Gemini 4 Carbon이나 Neon을 호출할 수 있나요?
2026년 11월 19일 기준으로는 호출할 수 없습니다. 테스트에서 두 ID 모두 Ofox에서 404 model_not_found를 반환했습니다. Ofox 목록에는 Gemini 4 Hydrogen과 Gemini 4 Argon이 있습니다. Carbon과 Neon은 Google 유료 등급을 사용하세요.