완벽한 응답만을 처리하는 코드는 이미 미래의 프로덕션 오류를 내포하고 있습니다. 이 코드는 리뷰를 통과하고, 데모를 마치고, 일주일 동안 잘 작동하다가, 제공업체가 429 오류를 반환하거나 모델 이름이 더 이상 수용되지 않는 순간에 무너집니다. 성공적인 요청은 탄력성(Resilience)의 증거처럼 보이지만, 이는 잘못된 증거입니다. 그것은 단지 이번에는 모든 것이 맞아떨어졌다는 것만을 보여줄 뿐입니다.

다음은 그 반대로 설계된 최소한의 어댑터(Adapter)에 대한 분석입니다. 이 어댑터는 먼저 예측 가능한 실패와 저렴한 구성 변경을 기술한 다음, 애플리케이션 로직(Application logic)을 처리합니다. 이러한 어댑터에 필요한 세 가지 계약 시나리오(Contract scenarios)는 일반적인 응답, 오류, 그리고 모델 구성 변경입니다. 각각은 별도로 검증되며, 결과는 로그(Log)에 기록됩니다.

로그가 바로 이 연습의 핵심입니다. 로그는 통합 지점(Integration points)을 '안정적인 지점(클라이언트가 스스로 처리 가능)'과 '처리가 필요한 지점(우리 코드 없이는 인시던트로 변함)'으로 구분해야 합니다. 이러한 구분이 없다면, "작동한다"와 "탄력적이다"는 같은 의미로 남게 됩니다.

왜 성공적인 응답은 나쁜 증거인가?

제가 반박하는 기본 관점은 다음과 같습니다: "요청이 200을 반환하고 의미 있는 텍스트를 돌려주었다면 통합 준비가 된 것이다." 준비가 되었다는 것은 수많은 시나리오 중 단 하나만을 처리할 준비가 되었다는 뜻입니다. OpenAI LLM API는 네트워크 장애, 제한 사항(Limits), 상태 코드(Status codes), 그리고 계속 변하는 모델 목록이 존재하는 표면입니다. 탄력성은 성공적인 호출이 아니라, 오류 시나리오가 재현되는지, 그리고 구성 변경 시 어떤 일이 발생하는지로 측정됩니다.

여기서 검증하고 반박할 수 있는 기준이 나옵니다: 만약 구성 변경이나 오류 처리를 위해 애플리케이션 로직을 수정해야 한다면, 어댑터는 자신의 계약을 이행하지 못한 것입니다. 이는 검증 가능합니다. 만약 다른 모델로 전환하기 위해 할인을 계산하거나 프롬프트(Prompt)를 생성하는 함수를 건드려야 한다면, 격리(Isolation)는 이루어지지 않은 것입니다.

좋은 소식은 공식 OpenAI SDK가 이미 이러한 계약을 구축할 수 있는 재료를 제공하고 있다는 점입니다. 오류 분류를 새로 발명할 필요는 없습니다. OpenAI 라이브러리가 우리를 대신해 이미 정의해 두었으므로, 우리는 자신의 코드에서 이를 관찰 가능(Observable)하게 만들기만 하면 됩니다.

openai 라이브러리는 필요한 재료를 기본적으로 제공합니다

openai/openai-python 리포지토리의 README(2026-07-18 접속)에 따르면, openai 라이브러리는 openai.APIError를 루트로 하는 구조화된 예외 계층(Exception Hierarchy)을 제공합니다. 이는 API로 가는 경로에서의 네트워크, 프록시 및 SSL 오류를 다루는 openai.APIConnectionError와, 2xx가 아닌 모든 응답에 대한 openai.APIStatusError로 나뉩니다. 후자는 .status_code와 .response를 제공합니다.

계층 구조 아래에는 특정 코드에 대해 별도로 임포트할 수 있는 하위 클래스들이 있습니다: BadRequestError (400), AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), UnprocessableEntityError (422), RateLimitError (429) 및 InternalServerError (>=500) (Developer Platform, 2026-07-18 접속). APITimeoutError는 별도로 존재하며, 요청이 설정된 타임아웃(Timeout)을 초과할 때 발생합니다.

또한 클라이언트는 일부 오류를 스스로 재시도(Retry)합니다. README에 따르면, 클라이언트는 기본적으로 연결 오류(Connection Error)와 HTTP 408, 409, 429 및 모든 500 이상의 응답에 대해 짧은 지수 백오프 (Exponential Backoff)를 적용하여 2번의 재시도를 수행합니다. 이는 OpenAI(max_retries=N)를 통해 전역적으로 설정하거나, .with_options(max_retries=N)를 통해 특정 호출에 대해 설정할 수 있습니다. 기본 요청 타임아웃은 10분이며, OpenAI(timeout=20.0) 또는 세밀하게 httpx.Timeout(...)을 통해 변경할 수 있습니다. 타임아웃이 발생한 요청도 여전히 기본 재시도 대상에 포함됩니다.

이러한 이름과 기본값들은 박물관의 전시물이 아닙니다. PyPI 데이터(2026-07-18 접속)에 따르면 openai 패키지의 최신 버전은 2026-07-17에 출시된 2.46.0입니다. 즉, 위의 예외 계층과 기본값들은 오래된 버전이 아닌 현재의 클라이언트 릴리스에 해당합니다. 코드를 실행하기 전에 버전 번호를 다시 한번 확인하십시오. README는 릴리스와 함께 업데이트됩니다.

최소 계약 어댑터 (Minimal Contractual Adapter): 코드 및 구조

OpenAI API Python 설치는 표준 방식인 pip install openai를 따르며, 그 다음 클라이언트와 필요한 에러 클래스들을 임포트합니다. 어댑터(Adapter)의 핵심 아이디어는 다음과 같습니다. OpenAI Python이 서비스 내에서 수행하는 모든 작업, 즉 모델 설정(Model configuration)과 에러 파싱(Error parsing)이 한 곳에서 이루어지며, 애플리케이션 코드(Application code)는 오직 좁은 범위의 메서드와 도메인에 특화된 명확한 예외(Exceptions)만을 보게 됩니다.

이를 가능하게 하는 핵심 사실은 model 파라미터가 클라이언트의 숨겨진 상태(Hidden state)가 아니라, 모든 호출(client.responses.create(model="...", input=...))에서 필수적인 명시적 인자(Explicit argument)라는 점입니다 (README 및 API reference, 2026-07-18 접근 기준). 즉, 모델 선택을 비즈니스 로직 전반에 흩뿌리는 대신 하나의 설정값으로 축약할 수 있습니다. 클라이언트 설정인 api_key, base_url, timeout, max_retries는 OpenAI(...)를 생성할 때 한 번만 지정하면 됩니다.

from openai import (
    OpenAI,
    APIConnectionError,
...

이제 애플리케이션 로직은 SDK의 가공되지 않은 클래스가 아닌 AdapterConfig와 AdapterBusy를 포착합니다. 이때 예외 체인(Exception chain)은 유실되지 않습니다. from e 구문을 통해 로그를 위한 원본 트레이스백(Traceback)을 보존하기 때문입니다. 이것이 바로 제공업체(Provider) 간의 차이점이 상위 계층으로 흘러나오지 않는, 실제 작동하는 OpenAI API 코드의 모습입니다. 규칙은 간단합니다. 프로젝트 내에서 이 클래스 외부에서 생성되는 OpenAI API 클라이언트는 단 하나도 없어야 합니다. 즉, OpenAI 클라이언트는 어댑터의 생성자(Constructor) 내에 존재하며 그 외의 곳에는 존재하지 않습니다.

이때 클라이언트는 단일 계약(Contract)이 아닌 여러 인터페이스(Surfaces)를 가지며, 각 인터페이스는 그에 맞는 시나리오를 필요로 합니다. OpenAI responses API는 텍스트 생성을 담당하고, OpenAI embeddings API는 벡터(Vectors)를 반환하며, OpenAI audio API는 오디오를 처리합니다. 응답 형식과 에러 세트가 서로 다르기 때문에, 텍스트 생성에 대해 통과한 하나의 테스트가 OpenAI embeddings API나 오디오로 자동 전이되지 않습니다.

공급업체 격리(Vendor isolation)는 단순히 보기 좋으라고 하는 것이 아닙니다. 이는 경로 교체를 사전에 저렴하게 만듭니다. 애플리케이션 코드가 아닌 단 하나의 base_url 값 수정만으로, 동일한 어댑터를 나중에 호환 가능한 러시아 엔드포인트로 리다이렉션할 수 있습니다. 바로 이 점 때문에 우리는 설정을 생성자(constructor)로 분리했습니다.

세 가지 계약 시나리오: 정확히 무엇을 검증하는가?

방법은 간단하며 의도적으로 좁게 설정되었습니다. 세 가지 테스트는 각각 '전반적으로 작동하는지'가 아니라 '기대하는 동작을 수행하는지'를 포착합니다.

시나리오 1 - 일반적인 응답. responses.create를 모킹(Mocking)하여, complete가 문자열을 반환하고 설정을 건드리지 않았는지 확인합니다. 이는 기본 사항이지만, 그 자체로 탄력성(resilience)을 증명하지는 않습니다.

시나리오 2 - 오류. 클라이언트가 RateLimitError와 AuthenticationError를 발생시키도록 강제하고, 어댑터가 이를 각각 AdapterBusy와 AdapterConfig로 변환했는지 확인합니다. 여기서 중요한 것은 정직한 경계 설정입니다. 문서에 따르면 429는 두 가지 다른 의미를 갖습니다. 즉, 속도 제한(throttling)과 할당량/결제 소진(quota/billing)입니다. 페이싱(Pacing) 429는 백오프(backoff)와 함께 재시도하지만, 할당량 429는 먼저 결제 문제를 해결해야 합니다. 다만 응답의 정확히 어떤 필드를 통해 원인을 구분해야 하는지는 문서에 명시되어 있지 않습니다. 이는 추측하는 것이 아니라, 자신의 계약 테스트(contract test)에서 실제 응답을 통해 직접 확인해야 합니다.

시나리오 3 - 구성 변경. 다른 model과 다른 base_url로 어댑터를 다시 구성하고, complete 메서드와 모든 애플리케이션 래퍼(application wrapper)가 단 한 줄도 변경되지 않았음을 확인합니다. 만약 변경을 위해 비즈니스 로직을 수정해야 했다면, 테스트는 실패(red)한 것이며 가설은 거짓으로 판명된 것입니다. 즉, 어댑터가 제 역할을 하지 못한 것입니다.

여기서 확실한 것과 그렇지 않은 것을 구분할 필요가 있습니다. 확실한 것: 계약 테스트는 어댑터의 기대 응답과 기대 오류를 포착하며, 이것이 어댑터의 직접적인 역할입니다. 그럴듯하지만 증명되지 않은 것: 어댑터 없는 직접 호출은 당신을 공급업체에 더 강하게 종속시킵니다. 그리고 응답 본문(response body)과 귀하의 환경이 반환할 코드는 실행 전까지는 아무도 알 수 없습니다. 이 글을 포함해서 말이죠.

모델 변경은 단순한 미적 수정이 아니라 장애 요인입니다

모델 이름을 하드코딩(Hardcode)하는 것은 실제 프로덕션 환경에서 장애를 일으키는 확실한 벡터이며, 이는 단순한 의견이 아닙니다. OpenAI의 폐기 정책(Deprecation Policy, Developer Platform, 2026-07-18 접속 기준)에 따르면 다음과 같은 라이프사이클 상태가 존재합니다: "Deprecated" - 모델이 새로운 요청을 받지 않음; "Sunset/Shut down" - 중단 날짜 이후 완전히 사용 불가능; "Legacy" - 업데이트되지는 않지만 여전히 호출 가능. Shutdown 이후에는 이전 이름으로 호출할 경우 오류가 발생합니다.

경고 기간은 최소 기준입니다: 공개 모델의 경우 최소 6개월, 특수 모델의 경우 최소 3개월, 프리뷰(Preview) 모델의 경우 약 2주 정도입니다. 보안 및 컴플라이언스(Compliance) 이슈로 인해 이 기간은 단축될 수 있습니다. 특정 모델의 실제 기간은 이 최소 기준보다 길 수 있으므로, 이 수치들을 모든 모델에 대한 약속으로 간주해서는 안 됩니다.

설계 측면에서의 실질적인 결론: 만약 OpenAI API 모델들이 나열되고 변경될 수 있으며, 모델 이름이 호출의 필수 인자(Argument)라면, 이를 하나의 설정값(Configuration value)으로 관리하십시오. 그렇게 하면 한 모델에서 다른 모델로 전환할 때 코드베이스를 뒤지는 대신, 설정값을 수정하고 시나리오 3을 한 번 실행하는 것만으로 충분합니다. OpenAI API 모델 목록은 영원할 것이라고 가정하지 말고, 릴리스 전에 반드시 재확인해야 합니다.

모델 변경은 비용 문제와도 직결됩니다. OpenAI API 가격(pricing)은 모델마다 다르기 때문에, 모델을 전환할 때는 품질뿐만 아니라 토큰당 OpenAI API 가격(price)도 고려해야 합니다. 러시아 팀의 경우 OpenAI API 가격에 더해 '어떻게 결제할 것인가'라는 두 번째 문제가 추가되는데, 이는 첫 번째 문제와 동일한 구성 수준에서 해결됩니다: provod.ai는 OpenRouter의 러시아 대안으로, 동일한 클라이언트와 동일한 OpenAI base URL을 사용하여 연결되며, 자체 마진 없이 모델 가격을 제공하고 단일 루블 잔액을 유지합니다. 실제 구현은 다음과 같습니다:

# 이전: 공식 경로
client = OpenAI(api_key=OPENAI_KEY)

...

호환 경로에 대한 중요한 주의사항: 호환 경로(compatible route)는 기본 API만 지원하며, 특정 공급업체의 공식 도구들에 비해 기능 면에서 뒤처집니다. 여기서 가역성(reversibility)은 존재하지만, 기능적인 측면에서 공짜는 아닙니다. 이 또한 머릿속에 담아두어야 할 기록의 한 줄이지, 당연하게 여길 사항은 아닙니다.

계약 시나리오 로그: '작동함'에서 '탄력적임'으로

로그(Log)는 이 방법론이 반드시 남겨야 하는 결과물로, 두 개의 열로 구성된 목록입니다. 왼쪽에는 클라이언트가 스스로 처리할 수 있는 안정적인 지점들이 있습니다: 네트워크 장애, 408/409/429 및 >=500 오류는 기본적으로(2회) 재시도(retry)하며, 타임아웃(timeout)은 자체 클래스로 포착합니다. 오른쪽에는 처리가 필요한 지점들이 있습니다: 401 오류는 클라이언트가 재시도하지 않으며, 우리의 매핑(mapping) 없이는 가공되지 않은 상태로 상위로 노출됩니다. 쿼터 제한(quota-429)은 조용히 재시도해서는 안 되며, model/base_url의 변경은 비즈니스 로직의 수정 없이 반드시 이루어져야 합니다.

바로 이 로그가 '작동함'과 '탄력적임(resilient)'을 구분합니다. 성공적인 응답에 대한 단 하나의 녹색 테스트만 있는 빈 로그는 이 글이 시작되었던 바로 그 상황입니다. 재현된 오류와 확인된 구성 변경이 포함된 채워진 로그야말로 리뷰에 가져갈 수 있는 결과물입니다.

다른 스택의 개발자들은 이곳에서 자신들의 래퍼(wrapper) — 예를 들어 JS 생태계의 ai sdk openai — 에 의존하지만, 이 원칙은 언어에 관한 것이 아닙니다. Python의 경우, 공식 라이브러리 위에 구축된 우리의 어댑터(adapter)가 래퍼의 역할을 수행하며, 그 계약(contract) 또한 동일합니다: 관찰 가능한 오류(observable error)와 저렴한 구성 변경(cheap configuration change)입니다.