504 오류: gemini-3.1-pro-preview-customtools 호출이 실패할 때 대처법

504는 게이트웨이가 상위 모델 응답을 기다리다 시간 초과했다는 뜻입니다. 요청은 전송되었지만 상위가 게이트웨이 제한 시간 안에 응답하지 않았습니다.

504 Gateway Timeout 은 게이트웨이가 upstream 응답을 기다리다 포기했다는 뜻입니다. 요청은 전달되었지만 게이트웨이 제한 시간 안에 결과가 오지 않았습니다. 출력을 줄이거나, 스트리밍으로 바꾸거나, max_tokens 를 낮추면 대부분 해결됩니다.

gemini-3.1-pro-preview-customtools 는 Google 가 제공하며, 이 페이지의 원인 분석·처리 방법·실측 데이터는 모두 게이트웨이 계층에서 이 모델의 실제 운영 상황을 바탕으로 정리했습니다.

이 게이트웨이에서 가장 흔한 원인은 「상위 응답이 게이트웨이 제한 시간을 초과함」입니다. 우선 처리할 동작은 「스트리밍 출력으로 바꾼다」입니다.

주요 원인

  • 상위 응답이 게이트웨이 제한 시간을 초과함
  • 긴 컨텍스트로 추론 시간이 늘어남
  • 상위 노드가 멈춤
  • 스트리밍 없이 출력이 매우 김

해결 방법

  • 스트리밍 출력으로 바꾼다
  • 컨텍스트를 줄이고 max_tokens를 낮춘다
  • 잠시 후 재시도한다
  • 추론이 더 빠른 모델을 사용한다

지수 백오프 재시도 예시

아래 코드는 gemini-3.1-pro-preview-customtools가 504를 반환할 때 최대 5회까지 재시도합니다. 대기 시간은 점점 길어지고 무작위 지터가 더해져 동시 재시도를 막습니다. base URL과 API 키는 환경 변수에서 읽고, 코드에 하드코딩하지 마세요.

import os, time, random
import requests

BASE  = os.getenv("OPENAI_BASE_URL")   # e.g. https://<your-gateway>/v1
KEY   = os.getenv("OPENAI_API_KEY")
MODEL = 'gemini-3.1-pro-preview-customtools'


def chat(messages, retries=5):
    """Retry with exponential backoff + jitter."""
    for i in range(retries):
        try:
            r = requests.post(
                BASE + "/chat/completions",
                headers={"Authorization": "Bearer " + KEY},
                json={"model": MODEL, "messages": messages, "stream": True},
                timeout=60,
            )
            if r.status_code == 429 or r.status_code >= 500:
                time.sleep(min(2 ** i + random.uniform(0, 1), 30))
                continue
            r.raise_for_status()
            return r.json()
        except requests.exceptions.Timeout:
            time.sleep(min(2 ** i + random.uniform(0, 1), 30))
    raise RuntimeError("gave up after " + str(retries) + " retries")


print(chat([{"role": "user", "content": "hello"}]))

이 모델의 핵심 데이터

API 엔드포인트https://api.airai.cc/v1
OpenAI 호환OpenAI-compatible
제공사Google
컨텍스트1M
지원 기능Reasoning, Tools, Files, Vision, Audio
API 형식openai, openai-response, openai-response-compact, anthropic, gemini, openai-alpha-search
과금 공식p * 2 + cr * 0.2 + c * 12) : tier("200k_plus", p * 4 + cr * 0.4 + c * 18

자주 묻는 질문

프론트엔드 직접 호출과 백엔드 경유 중 어디서 504 가 더 잘 발생하나요?

예비 모델도 함께 준비해 두세요. 아키텍처 수준에서 폴백을 두는 편이 오류를 하나씩 고치는 것보다 안정적입니다. Google 의 이 모델에는 게이트웨이가 전환할 수 있는 upstream 노드가 여러 개 있습니다. 더 가벼운 예비 모델을 준비해 두면 주 흐름이 끊기지 않습니다.

gemini-3.1-pro-preview-customtools의 504는 계정 할당량과 관련이 있나요?

주로 할당량 문제이며 모델 자체의 고장이 아닙니다. 요금제 한도를 높이거나 호출 빈도를 낮추는 것 모두 도움이 됩니다. 과금은 p * 2 + cr * 0.2 + c * 12) : tier("200k_plus", p * 4 + cr * 0.4 + c * 18 방식을 따르며 출력이 없으면 청구되지 않습니다. 과금 방식이 p * 2 + cr * 0.2 + c * 12) : tier("200k_plus", p * 4 + cr * 0.4 + c * 18 인 경우, 실패한 요청은 사용량에 포함되지 않습니다. 먼저 콘솔에서 잔액과 속도 제한을 확인한 뒤 코드를 살펴보세요.

504 로 인해 데이터가 유실될 수 있나요?

이 오류는 모델 성능과 무관하며 게이트웨이 계층의 문제입니다. 대부분 일시적인 문제이며 스스로 복구됩니다. 이 모델의 기능 태그는 Reasoning, Tools, Files, Vision, Audio 입니다. 몇 분 이상 지속되면 플랫폼 고객센터에 연락해 업스트림 상태를 확인하세요. 먼저 계정 수준인지 모델 수준인지 판단하세요. 두 경우의 대응은 완전히 다릅니다.

504 은 gemini-3.1-pro-preview-customtools 의 과금 방식과 관련이 있나요?

청구되지 않습니다. 실제로 생성된 출력만 사용량에 반영됩니다. 이미 생성된 부분만 과금되고, 실패한 부분은 과금되지 않습니다. 입력 단가는 대략 $2.00 / 백만 토큰입니다. 먼저 콘솔에서 잔액과 속도 제한을 확인한 뒤 코드를 살펴보세요. p * 2 + cr * 0.2 + c * 12) : tier("200k_plus", p * 4 + cr * 0.4 + c * 18 로 비용을 추산할 때는 재시도 예산도 포함하세요.

이 모델의 다른 오류

같은 오류가 나는 다른 모델

모델 페이지로 돌아가기

데이터 업데이트: 2026-10-10 15:45

기술 지원온라인 상담
맨 위로