Nano Banana Pro 503 오류 해결: Deadline 메시지 구분과 재시도 중단 기준

Nano Banana Pro 이미지 API에서 HTTP 503과 UNAVAILABLE을 받았다면, 같은 요청을 안전하게 다시 보낼 수 있는지 확인한 뒤 기다렸다가 제한된 횟수만 재시도합니다. 메시지에 Deadline expired가 들어 있어도 곧바로 504로 판단하거나 타임아웃만 늘리지 않습니다. 반대로 아무 응답도 받지 못한 연결 끊김은 503으로 분류하지 않습니다. 서버에서 이미 이미지를 생성했을 수 있으므로 원래 작업의 결과부터 확인해야 합니다.

여기서 복구란 같은 API·모델·입력·출력 조건으로 사용할 수 있는 이미지가 돌아오는 것입니다. 200 응답, 대기열 등록, 다른 모델의 1K 이미지 중 하나만 확인하고 원래 Pro 4K 작업이 해결됐다고 처리하면 안 됩니다.

2026년 10월 7일 기준 Google의 공식 Pro 모델 ID는 gemini-3-pro-image입니다. 예전 오류 사례에 등장하는 gemini-3-pro-image-preview는 과거 모델이며, 공식 지원 종료 일정과 현재 모델을 구분해야 합니다. 기존 generateContent도 지원되므로 503을 조사하는 도중에 Interactions API로 갈아탈 필요는 없습니다. 모델 전환 일정, Interactions 안내

Deadline expired가 보여도 응답 코드부터 확인합니다

먼저 실패한 요청의 호출 주소, HTTP 상태, 오류 본문과 경과 시간을 함께 확인합니다. Google API가 보낸 오류인지, 사용하는 중계 API가 보낸 오류인지, 앱 서버가 자체적으로 반환한 오류인지도 구분합니다. 앱의 HTML 오류 페이지에 503이 찍혔다고 Google 모델이 503을 반환했다고 단정할 수는 없습니다.

API마다 error.code의 형식도 다릅니다. Google의 기존 generateContent 응답과 Python SDK 오류 객체는 정수 코드를 사용하지만, Interactions 오류 본문에는 service_unavailable 같은 문자열 코드가 들어갑니다. 문자열을 정수 503과 비교하면 재시도 분기가 작동하지 않습니다. Google API 오류 문서, Python SDK 오류 객체

HTTP 503은 일시적인 서비스 불가를 뜻하며 과부하나 유지 보수가 원인일 수 있습니다. 다만 그 코드만으로 GPU 부족, 내부 대기열의 길이, 전체 Google 장애까지 알 수는 없습니다. HTTP 504는 게이트웨이의 응답 대기 실패입니다. HTTP 503 정의, HTTP 504 정의

다음은 과거 Google 개발자 포럼 사례에서 확인된 오류 조합입니다. 식별용으로 축약한 JSON이며 실행할 요청은 아닙니다.

{
  "error": {
    "code": 503,
    "message": "Deadline expired before operation could complete.",
    "status": "UNAVAILABLE"
  }
}

2025년 12월부터 2026년 1월까지 이어진 이 포럼 사례는 Deadline 문구와 503이 함께 나올 수 있음을 보여 줍니다. 특정 내부 원인이나 현재 복구 시간을 입증하지는 않습니다. 오류 본문의 지정된 필드를 읽어야 하며, 프롬프트나 전체 로그에서 503 또는 deadline이라는 글자를 검색해 분류해서는 안 됩니다.

503 재시도는 대기 시간·횟수·전체 시간을 함께 제한합니다

같은 요청으로 회복을 확인하려면 우선 모델, 호출 주소, 프로젝트, 프롬프트와 참조 이미지, 출력 크기를 유지합니다. 여러 조건을 한꺼번에 바꾸면 성공하더라도 무엇이 달라졌는지 알 수 없습니다.

재시도에 앞서 요청이 원래 적용되지 않았음을 확인할 수 있는지, 또는 해당 서비스가 재전송을 안전하게 처리한다고 문서로 보장하는지 살핍니다. 이미지 생성 POST 요청은 자동으로 멱등성을 갖지 않습니다. 앱에서 같은 작업 ID를 붙여도 서버가 중복 생성을 방지해 준다는 뜻은 아닙니다. 처리 여부가 불명확하면 아래의 ‘응답 없이 타임아웃’ 절차로 넘어갑니다. HTTP 재시도와 멱등성

안전하게 재전송할 수 있는 503이라면 다음 순서로 처리합니다.

1. 서버의 대기 지시를 확인합니다. Retry-After가 있으면 초 단위 정수인지 HTTP 날짜인지 구분해 남은 대기 시간을 계산합니다. 서버가 120초 뒤에 보내라고 했는데 화면에서 20초만 기다릴 수 있다면, 20초 뒤에 다시 보내지 말고 작업을 나중으로 미룹니다.
2. 대기를 늘리고 시점을 분산합니다. 대기 간격을 점차 늘리는 백오프와 무작위 대기인 지터를 사용합니다. 동시에 실패한 작업들이 같은 순간에 다시 몰리지 않게 하려는 조치입니다.
3. 한 번 보낼 때마다 결과를 다시 분류합니다. 503이 유지되는지, 504나 429로 바뀌는지, 실제 이미지가 돌아왔는지 확인합니다. 처음 오류가 503이었다고 이후의 모든 실패에 같은 규칙을 적용하지 않습니다.
4. 횟수 또는 전체 시간 한도에 닿으면 중단합니다. 대기뿐 아니라 API 호출에 걸린 시간까지 합산합니다. 다음 요청이 끝날 시간을 확보할 수 없으면 새 요청을 시작하지 않습니다.

백오프·지터·최대 횟수는 Google 문제 해결 가이드가 안내하는 원칙입니다. 아래 수치는 동작을 설명하기 위한 앱 설정 예시이며, Google의 필수 값이나 Pro 처리 시간 보장은 아닙니다.

다음 요청을 보낼지 결정하는 로컬 예시

이 함수는 이미 재전송해도 안전한 503으로 분류한 뒤 사용합니다. API나 SDK를 호출하지 않고, 다음 요청 전의 대기 시간 또는 중단 결정을 반환합니다. attempts는 최초 요청을 포함한 완료 횟수, elapsed는 최초 전송부터 단조 시계로 잰 전체 경과 시간입니다. retry_after는 HTTP 헤더를 해석한 뒤 초로 환산한 값이고, jitter는 호출부에서 매번 새로 고르는 0 이상 1 미만의 값입니다.

import math


def next_503_action(attempts, elapsed, retry_after=None, jitter=0.5):
    # 설명용 설정: 최초 요청 포함 4회, 전체 75초, 다음 호출에 20초 확보
    max_attempts, total_seconds, call_seconds = 4, 75.0, 20.0
    if type(attempts) is not int or attempts < 1:
        raise ValueError("attempts는 최초 요청을 포함한 양의 정수입니다.")
    if not math.isfinite(elapsed) or elapsed < 0:
        raise ValueError("elapsed는 0 이상의 유한한 초 값입니다.")
    if not math.isfinite(jitter) or not 0 <= jitter < 1:
        raise ValueError("jitter는 0 이상 1 미만입니다.")
    if retry_after is not None:
        if not math.isfinite(retry_after) or retry_after < 0:
            raise ValueError("retry_after는 0 이상의 유한한 초 값입니다.")
    if attempts >= max_attempts:
        return ("defer", None)
    wait = min(2 ** (attempts - 1), 8) * jitter
    if retry_after is not None:
        wait = max(wait, retry_after)
    if elapsed + wait + call_seconds > total_seconds:
        return ("defer", None)
    return ("retry", wait)


print(next_503_action(1, 12, jitter=0.5))  # ('retry', 0.5)
print(next_503_action(1, 12, retry_after=120))  # ('defer', None)
print(next_503_action(4, 40))  # ('defer', None)

연결할 때는 최초 요청 전에 시작 시각을 기록하고, 각 응답 뒤에 횟수를 증가시킵니다. retry이면 반환된 시간만큼 기다린 뒤 전체 남은 시간을 다시 확인합니다. 예시의 호출당 20초 제한도 호출부에서 실제로 적용해야 합니다. 함수만 붙여 놓고 요청을 무제한 기다리면 75초 한도가 지켜지지 않습니다. 대기 중 취소되거나 예정된 시각보다 늦게 깨어났다면 남은 시간을 다시 계산합니다.

Retry-After 날짜 계산에는 벽시계를, 전체 경과 시간에는 단조 시계를 사용합니다. 이미 지난 날짜는 대기 0초로 처리할 수 있지만, 해석할 수 없는 헤더를 임의의 짧은 시간으로 바꾸어 서버 지시를 읽은 것처럼 처리하지 않습니다. Retry-After 형식

이 예시는 문법과 합성 입력에 대한 분기만 로컬에서 확인했습니다. 실제 API의 수락 여부, 이미지 생성 속도나 청구액을 시험한 코드는 아닙니다.

SDK와 앱이 동시에 재시도하지 않도록 합니다

재시도 담당은 한 곳으로 정합니다. 앱에서 최대 4회로 제한해도 SDK와 중계 서버가 각각 다시 보내면 실제 생성 요청 수는 더 많아질 수 있습니다. 설정에서 각 계층의 재시도를 확인하고, 앱이 담당한다면 지원되는 설정으로 내부 재시도를 제한합니다.

Google 문제 해결 문서는 Python SDK의 자동 재시도를 설명하지만, 2026년 10월 6일 확인한 공개 main 소스에서는 retry_options=None일 때 한 번 시도하고, 옵션을 명시한 경우에 별도 기본 횟수를 적용했습니다. 이 소스는 10월 7일에 로컬로 다시 읽은 스냅샷이며 설치된 패키지의 동작을 확인한 결과가 아닙니다. 사용 중인 버전과 설정을 기준으로 판단해야 합니다. 같은 스냅샷의 HttpOptions.timeout 단위는 밀리초, 재시도 간격은 초입니다. 단위를 혼동하면 의도한 대기 시간이 달라집니다. SDK 재시도 구현, HTTP 옵션 정의

계속 503이면 즉시 재시도를 멈추고 작업을 보존합니다

정한 횟수나 시간 한도에 닿았다면 사용자에게 처리 지연을 알리고 남은 작업을 대기열로 넘깁니다. 대기열 등록은 완료가 아니므로 ‘이미지 생성 성공’과 별도 상태로 표시합니다. 다음 실행 시각, 전체 시도 한도와 작업 만료 시각도 정해야 대기열에서 무한 반복하는 문제가 생기지 않습니다.

여러 작업이 함께 실패한다면 신규 전송을 잠시 줄이고 소수의 요청으로 회복 여부를 확인합니다. 이것은 앱의 부담을 줄이는 운영 선택이며 Google의 숨겨진 동시 요청 한도를 밝혀낸 결과는 아닙니다. 공개 상태 안내와 해당 공급자의 공지도 확인하고, 장애가 계속되면 필요한 기록을 준비합니다.

기록에는 시각과 시간대, 호출 주소, 모델 ID, 출력 크기, HTTP 상태·오류 코드, 요청 식별자, 경과 시간과 시도 횟수를 남깁니다. API 키, 인증 헤더, 비공개 프롬프트와 참조 이미지 원본은 공유 로그에서 제외합니다. 이 정도면 여러 요청이 같은 증상으로 실패했는지 비교할 수 있습니다.

유료 가입이나 티어 상승을 503의 확정 해결책으로 삼지는 않습니다. 2025년 유료 Tier 1의 4K 사례에서도 503 과부하가 보고됐습니다. 당시 작성자는 같은 날 회복을 알렸지만, 모든 계정에 적용되는 복구 시간이나 현재 4K 제한을 뜻하지 않습니다.

504와 응답 없는 타임아웃은 따로 조사합니다

504를 받았다면 어느 서비스의 대기 시간이 먼저 끝났는지 확인합니다. 클라이언트, 앱 서버, 중계 API와 모델 API의 제한은 서로 다를 수 있습니다. 이미 서버가 504나 Deadline 오류를 반환했다면 클라이언트의 대기 시간을 늘려도 그 요청이 다시 살아나지는 않습니다. 다음 호출을 위한 설정을 바꾸는 것입니다.

요청이 끝나기 전에 클라이언트의 짧은 제한만 만료된다는 근거가 있고 다른 구간에 여유가 있다면 클라이언트 제한을 조정할 수 있습니다. 참조 이미지나 출력 크기를 줄이는 비교도 가능하지만 한 번에 한 조건씩 바꿉니다. 4K가 필요한 작업에서 2K로 성공한 것은 처리 조건을 좁혀 본 결과이며 원래 4K 요청의 복구가 아닙니다. Pro는 사고 기능을 끌 수 없으므로 일반적인 ‘thinking 끄기’ 조언도 그대로 적용할 수 없습니다. Pro 모델 사양

HTTP 응답을 받지 못했다면 처리 결과는 미확정입니다. 클라이언트가 기다리기를 중단한 뒤에도 서버는 작업을 끝냈을 수 있습니다. 사용하는 서비스가 작업 조회나 결과 확인 기능을 제공한다면 기존 식별자로 먼저 확인합니다. 이전 요청과 연결된 앱 기록이나 이미 저장된 결과도 살펴봅니다. 확인 기능이 없고 처리 여부를 알 수 없다면 자동 재전송을 멈추고, 중복 생성과 추가 비용 가능성을 감수할지 별도로 결정합니다.

동일한 프롬프트, 자체 작업 ID 또는 추적용 요청 ID는 Google의 자동 중복 제거를 보장하지 않습니다. 문서에 없는 Idempotency-Key 헤더를 추가하는 것으로 이 문제를 해결했다고 판단하지 않습니다. 비멱등 요청의 재시도 조건

같은 요청의 실제 이미지가 돌아와야 복구입니다

재시도 후에는 오류만 사라졌는지보다 필요한 결과가 생겼는지를 확인합니다.

• 호출 조건이 같은가: 공급자와 API, 모델, 입력과 필요한 출력 크기를 유지했는지 확인합니다.
• 이미지 블록이 있는가: 기존 generateContent는 candidates의 content.parts.inlineData, Interactions는 steps의 모델 출력 안에 있는 이미지 블록을 읽습니다. 두 응답 형식을 섞지 않습니다.
• 이미지 데이터가 사용 가능한가: 실제 MIME을 확인하고 base64 데이터를 해석해 파일로 저장한 뒤, 이미지로 열 수 있는지 확인합니다. 여러 이미지를 받았다면 필요한 결과가 모두 있는지도 봅니다.
• 작업 조건을 충족하는가: 저장만 됐다고 끝내지 말고 필요한 크기와 내용, 납기 조건을 확인합니다. 지연 후 받은 이미지는 저장하더라도 시간 안에 완료된 작업과 구분합니다.

HTTP 200인데 텍스트만 왔거나 이미지가 없으면 이미지 작업의 성공으로 표시하지 않습니다. 안전성 차단, no_image, 응답 형식·저장 코드 문제를 구분하고, 동일한 503 재시도에 계속 넣지 않습니다. 이미지 저장 구현은 공식 요청 형식과 이미지 저장 안내에서 이어 볼 수 있습니다. 공식 이미지 응답 설명, 이미지 관련 오류

모델이나 공급자를 바꾸는 방법은 납기와 요구 사양을 다시 정할 수 있을 때 고려합니다. 호출 주소·인증·요청·응답 형식, 실제 출력 크기와 과금·데이터 보존 조건을 새로 확인해야 합니다. 다른 곳에서 성공한 결과는 대체 작업의 성공이며 원래 Google Pro 요청의 회복을 증명하지 않습니다.

오류가 바뀌면 다음 확인 대상도 바꿉니다

Interactions의 세부 문자열 코드는 Google API 오류 문서에서 확인합니다. 할당량은 프로젝트 기준으로 적용되므로 429를 새 키 발급으로 해결하려고 하면 같은 프로젝트의 한도를 다시 만날 수 있습니다. 할당량 적용 기준

자주 묻는 질문

Deadline expired before operation could complete가 뜨면 타임아웃을 늘려야 하나요?

메시지만으로 결정하지 않습니다. HTTP 503·UNAVAILABLE이면 먼저 안전한 재전송과 제한된 대기를 판단합니다. 실제 504라면 초과된 구간을 확인하고, 응답 없는 클라이언트 타임아웃이라면 기존 작업의 처리 결과부터 확인합니다. 503과 Deadline이 함께 나온 과거 사례

몇 초 기다리면 반드시 해결되나요?

보장된 시간은 없습니다. Retry-After가 있으면 그 지시를 지키고, 없으면 백오프와 지터를 사용하되 앱의 횟수·전체 시간 한도에서 멈춥니다. 위의 4회·75초는 예시 설정이며 Google의 복구 약속이 아닙니다. 재시도 원칙, Retry-After

Pro 4K에서만 실패하면 2K로 낮춰야 하나요?

2K로도 목적을 달성할 수 있을 때는 별도 대체 작업으로 시도할 수 있습니다. 4K가 필수라면 요구 조건을 그대로 두고 연기하거나 다른 검증된 경로를 검토합니다. 2K 성공만으로 4K 과부하가 풀렸다고 판단할 수는 없습니다. 공식 Pro는 1K·2K·4K를 지원합니다. Pro 사양

503으로 실패한 요청은 모두 무료인가요?

503이라는 상태만으로 무료나 환불을 보장할 수 없습니다. 오류를 보낸 서비스, 실제 처리 결과와 해당 과금 규칙을 확인해야 합니다. 특히 응답 없이 타임아웃된 요청은 이미 생성됐을 가능성이 있으므로 재전송 시 중복 비용도 고려합니다. 이미지 출력 외 입력·텍스트 등의 요금도 별도로 적용될 수 있습니다. Google 가격표

503이 429로 바뀌면 문제가 해결된 건가요?

이미지 작업은 아직 완료되지 않았습니다. 이제는 과부하 재시도보다 실제 할당량 제한을 조사할 차례입니다. Gemini 이미지 429 안내에서 분당·일일·지출 한도에 해당하는 부분을 확인합니다. 모델 선택이나 출력 사양을 바꾸기 전에는 현재 공식 모델과 지원 일정도 함께 확인합니다.