Nano Banana API가 실패하면 먼저 오류 분기를 정해야 합니다. 429 RESOURCE_EXHAUSTED는 프로젝트나 모델의 한도 압박입니다. 503 UNAVAILABLE은 용량 또는 일시적 가용성 문제입니다. 504 DEADLINE_EXCEEDED는 timeout 분기입니다. HTTP 성공인데 이미지가 없으면 response parts, inlineData, output modality, safety finish, file reference를 확인해야 합니다. 요청 거부 문구는 permission, safety, key/project, file access, gateway policy로 나누어야 합니다.
| 현상 | 첫 안전 확인 | 다음 조치 |
|---|---|---|
429 RESOURCE_EXHAUSTED | 현재 project와 model의 실제 한도를 확인합니다. | jitter가 있는 backoff, queue, 또는 429 전용 경로로 이동합니다. |
503 UNAVAILABLE / 504 DEADLINE_EXCEEDED | 같은 model, endpoint, project, key, payload, input으로 재검증합니다. | 503은 용량, 504는 timeout 또는 부하를 수정합니다. |
| 이미지 없음 또는 text only | 모든 response parts에서 image data를 찾습니다. | parser, modality, safety, file reference를 고칩니다. |
| 요청 거부 | 403, blocked key, safety finish, file resource, gateway denial을 분리합니다. | 거부한 owner만 수정합니다. |
팩트 기준: Google Gemini API troubleshooting, image generation, rate limits, Batch API, Files API 문서는 2026년 4월 19일에 확인했습니다. 오래된 quota 표, 특정 시간대 보장, 오류율 숫자, 무조건 해결 표현은 사용하지 않습니다.
429 RESOURCE_EXHAUSTED는 먼저 한도 문제로 봅니다
429 RESOURCE_EXHAUSTED는 먼저 quota 또는 rate limit입니다. 같은 project 안의 다른 API key로 바꿔도 project-level 제한은 그대로일 수 있습니다. 그래서 key 회전보다 project와 model의 현재 한도 확인이 먼저입니다.
확인 후에는 시도 횟수가 제한된 backoff를 사용합니다. 여러 worker가 동시에 돌아오지 않도록 jitter를 넣고, 실패한 요청의 원본 status를 로그에 남깁니다. 실시간이 아닌 이미지 작업은 동기 요청과 같은 한도를 쓰지 않도록 queue나 Batch API로 옮기는 편이 낫습니다.
정상 사용에서도 429가 반복되면 재시도 문제가 아니라 처리량 설계 문제입니다. 자세한 흐름은 Gemini Image 429 rate limit, 넓은 한도 설계는 Gemini API rate limits가 맞습니다.
503과 504는 같은 처방이 아닙니다
503 UNAVAILABLE은 일시적 가용성 또는 용량 분기입니다. 아직 billing, key, prompt가 원인이라고 말할 수 없습니다. 같은 경로로 한 번 재검증하세요. 여전히 503이면 용량 분기가 유지됩니다. 429로 바뀌면 한도 분기로 이동하고, 400/403으로 바뀌면 client branch로 전환합니다.
504 DEADLINE_EXCEEDED는 시간 예산을 넘긴 것입니다. input이 너무 크거나, generation이 복잡하거나, client timeout이 짧거나, backend가 느릴 수 있습니다. 504에는 빠른 반복 재시도보다 timeout 상향, payload 축소, input file 정리가 더 중요합니다.
지속적인 503/504는 Gemini 3 Pro Image 503 overloaded 경로로 넘겨 용량과 timeout 증거를 분리하세요.
이미지 없음은 response parts 확인부터 시작합니다
HTTP 성공이어도 이미지 part가 없을 수 있습니다. 애플리케이션이 첫 text part만 읽거나 고정된 필드만 저장하면 실제 image part를 놓치거나, 반대로 image part가 없는데 성공으로 표시할 수 있습니다.
모든 candidate와 content part를 순회하고 inlineData와 image MIME type을 찾으세요. 없다면 image output을 요청했는지, safety finish가 있었는지, input file이 API에서 접근 가능한 resource인지, gateway가 response를 변환하지 않았는지 확인합니다.
이 분기에서는 parser 수정만으로 해결되는 경우가 많습니다. image part만 저장하고, text part와 finish reason은 별도 로그로 남기며, file URI는 같은 project에서 접근 가능한 값으로 유지합니다.
요청 거부는 여러 owner로 나뉩니다
요청 거부는 하나의 오류명이 아닙니다. 403 PERMISSION_DENIED는 key, project, API enablement, permission 문제입니다. HTTP 성공과 함께 finishReason: SAFETY가 오면 safety branch입니다. 파일 입력을 쓰는 요청이라면 file name, URI, MIME type, state, project ownership을 확인합니다. gateway를 쓰면 upstream status와 gateway status를 분리해서 기록해야 합니다.
모든 값을 동시에 바꾸면 원인을 잃습니다. 권한이면 권한을, safety면 prompt나 policy를, file이면 resource reference를, gateway면 gateway auth와 policy를 수정하세요.
같은 경로 재검증이 원인 신호를 지킵니다
같은 경로 재검증에서는 model, endpoint, project, key, payload, input asset, request format을 고정합니다. 그 상태에서 분기가 유지되는지, 다른 분기로 바뀌는지를 봅니다.
| 재검증 결과 | 의미 | 조치 |
|---|---|---|
| 계속 429 | 한도 분기가 안정적 | backoff, queue, Batch API, 429 route |
| 계속 503 | 용량 분기가 안정적 | bounded retry, queue, 503 route |
| 504로 변경 | timeout이 드러남 | timeout 상향 또는 부하 축소 |
| 성공하지만 이미지 없음 | response shape가 드러남 | parts, inlineData, modality, safety, file 확인 |
| 403 또는 거부로 변경 | permission/safety/file이 드러남 | 해당 owner 수정 |
분기가 확인된 뒤에만 한 번에 하나의 변수를 바꾸세요. 지속적인 429라면 Nano Banana 2 alternative 429를 검토할 수 있습니다.
자주 묻는 질문
503이면 Nano Banana API 전체 장애인가요?
아닙니다. 현재 요청 경로가 availability 또는 capacity 분기에 들어갔다는 뜻입니다. 같은 경로 재검증과 다른 model/endpoint 비교가 먼저입니다.
결제를 켜면 503이 해결되나요?
결제와 tier는 429 한도에 영향을 줄 수 있지만, 증명된 503 capacity branch를 자동으로 고치지는 않습니다.
텍스트는 오는데 이미지가 없는 이유는 무엇인가요?
parser가 image part를 읽지 않았거나, image output을 요청하지 않았거나, safety finish가 있었거나, input file을 API가 읽을 수 없을 수 있습니다.
요청 거부는 어디부터 봐야 하나요?
HTTP status부터 봅니다. 403이면 key/project/permission, success와 safety finish면 safety, file 입력이면 resource URI와 ownership을 확인합니다.
언제 model이나 provider를 바꿔야 하나요?
오류 분기가 증명된 뒤입니다. 지속적인 429, 지속적인 503, safety limit, file/gateway policy가 확인될 때만 route 변경을 검토하세요.