OpenAI 호환 Base URL을 잘못 입력했을 때 SDK가 계속 404 오류를 내는 이유

OpenAI 호환 (OpenAI-compatible) API를 연결할 때 가장 흔히 오판하기 쉬운 문제는 404입니다.

많은 사람들이 404를 보면 서비스가 사용 불가능하거나 SDK 버전이 잘못되었다고 생각합니다. 하지만 실제로는 Base URL, 경로 접두사 (path prefix), 모델명, 그리고 인터페이스 유형이 일치하지 않는 경우가 훨씬 더 흔합니다.

이 글은 오직 한 가지 일만 합니다: 404 오류의 점검 순서를 명확하게 설명하는 것입니다.

첫 번째: /v1을 제대로 작성했는지 확인

OpenAI SDK는 보통 당신이 제공한 base_url 뒤에 인터페이스 경로를 계속 이어 붙입니다. 만약 호환 게이트웨이가 요구하는 엔트리 포인트가 다음과 같다면:

https://api.example.com/v1

당신은 전체 /v1을 함께 작성해야 합니다.

만약 루트 도메인만 작성한다면:

https://api.example.com

SDK는 잘못된 경로로 요청을 보낼 수 있습니다. 오류 증상은 404일 수도 있고, 인증 실패처럼 보일 수도 있습니다.

최소 테스트 코드는 다음과 같이 작성할 수 있습니다:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.example.com/v1",
    api_key="your-api-key"
)

먼저 이 코드를 성공시킨 후, 당신의 비즈니스 코드를 연결하세요.

두 번째: 모델명이 현재 사용 가능한 이름인지 확인

model not found 오류도 자주 404로 포장되어 나타납니다.

기억에 의존해서 모델명을 쓰지 마세요. 예를 들어 gpt-5.5를 사용하고 싶다면, 모델 리스트에서 현재 노출된 이름을 복사해서 사용해야 합니다. 버전 번호, 하이픈 (-), 대소문자, 별칭(alias) 모두 요청 실패의 원인이 될 수 있습니다.

기존 프로젝트를 마이그레이션 중이라면, 특히 코드 내 여러 곳에 모델명이 하드코딩되어 있는지 확인해야 합니다. 가장 놓치기 쉬운 부분은 다음과 같습니다:

• .env 파일
• Docker Compose
• CI 설정
• 프론트엔드 예시 코드
• 백엔드 기본 파라미터
• 테스트 스크립트

한 곳만 수정해서는 부족합니다. 모든 진입점(entry point)을 통일해야 합니다.

세 번째: 인터페이스 유형이 일치하는지 확인

어떤 모델은 Chat Completions에만 적합하며, 어떤 인터페이스는 다른 요청 형식을 요구할 수 있습니다. Chat SDK를 사용하여 해당 인터페이스 유형을 지원하지 않는 모델을 호출하면, 명확하지 않은 오류를 받을 수 있습니다.

점검할 때는 먼저 복잡한 요청을 사용하지 마세요. 스트리밍 (stream), 도구 호출 (tool calling), JSON 모드 (JSON mode), 긴 컨텍스트 (long context)를 모두 끄고, 먼저 일반적인 Chat 요청을 보내보세요. 일반 요청이 성공하면, 하나씩 다른 기능들을 켜보시기 바랍니다.

네 번째: 환경 변수가 덮어쓰여지지 않았는지 확인

많은 프로젝트에서 문제는 코드가 틀린 것이 아니라, 실행 시점에 읽어들이는 환경 변수가 당신이 생각하는 값과 다른 경우입니다.

실행 시점에 민감하지 않은 설정을 출력해 보는 것을 권장합니다:

import os

print("base_url =", os.getenv("AI_API_BASE_URL"))

API Key는 출력하지 마세요. Base URL과 모델명만 확인하면 충분합니다.

Cursor, Cline, Docker, 클라우드 함수(Cloud Functions) 또는 PM2를 사용하는 경우, 이러한 실행 환경이 현재 터미널의 변수를 자동으로 읽어오지 않을 수 있다는 점을 기억하세요.

다섯 번째: 상태 페이지와 요청 로그 확인

어제까지 잘 작동했는데 오늘 갑자기 404가 발생한다면, 서둘러 코드를 수정하지 마세요.

두 가지를 확인하세요:

• 상태 페이지(status page)에 모델 유지보수나 상위 서비스(upstream)의 변동이 있는지.
• 요청 로그(request logs)에 실제로 요청된 모델명과 경로가 무엇인지.

Wappkit의 연동 설명은 docs를 먼저 참조할 수 있으며, 모델 이름은 model list를 기준으로 합니다. 로그에서 요청 경로, 모델명, 오류 메시지를 볼 수 있다면 점검 속도가 훨씬 빨라질 것입니다.

간단한 점검 순서

404를 만났을 때, 다음 순서대로 진행할 수 있습니다:

1. Base URL에 올바른 /v1이 포함되어 있는가.
2. API Key가 현재 게이트웨이에 속해 있는가.
3. 모델명이 현재 모델 리스트에서 복사한 것인가.
4. 인터페이스 유형이 일치하는가.
5. 환경 변수가 실행 환경에 의해 덮어쓰여지지 않았는가.
6. 상태 페이지와 요청 로그에 이상이 표시되는가.

이 6단계는 무작정 SDK를 교체하는 것보다 훨씬 효과적입니다.

요약

OpenAI 호환 Base URL의 404 오류는 대부분 신비로운 고장이 아닙니다.

대개 경로 접두사, 모델명, 인터페이스 유형 또는 실행 환경 설정의 불일치에서 발생합니다. 최소한의 요청을 먼저 성공시킨 후, 단계적으로 비즈니스 코드로 복귀하면 문제가 훨씬 명확해질 것입니다.