Python으로 공부하는 OpenAI 32편 — FastAPI + OpenAI B2B SaaS, 장애 대응과 SLA는 어디까지 준비해야 할까?

Python으로 공부하는 OpenAI 32편 — FastAPI + OpenAI B2B SaaS, 장애 대응과 SLA는 어디까지 준비해야 할까?

한 줄 요약

FastAPI + OpenAI 기반 B2B SaaS를 운영한다면, 고객에게 가장 먼저 보여줘야 하는 건 “문제가 안 난다”가 아니라 문제가 났을 때 어떻게 감지하고, 어떻게 축소하고, 무엇을 고객에게 설명할 수 있는가입니다. OpenAI는 새 프로젝트에 Responses API를 권장하고, 운영 단계에서 production best practices, rate limits, request IDs, background mode, status page, support 전달 정보 같은 운영 요소를 따로 안내합니다. 또 일반 API 전체에 대한 공개 latency SLA는 별도로 준비 중이라고 Help Center에 적혀 있고, Enterprise 고객용 Priority processing에는 99.9% uptime SLA와 latency SLA가 문서화돼 있습니다. (developers.openai.com (OpenAI Help Center))

---

왜 이 글이 중요한가?

B2B 고객이 붙기 시작하면 질문이 달라집니다.

이제는
“RAG 되나요?”
보다
“장애 나면 누가 대응하나요?”
“현재 상태는 어디서 확인하나요?”
“request ID 같은 추적 정보 남기나요?”
“긴 작업이 느리면 어떤 우회 경로가 있나요?”
이런 질문이 더 자주 나옵니다.

저도 이 구간에 와서 느꼈는데요.
기능이 꽤 괜찮아도, 운영 설명이 빈약하면 서비스가 갑자기 미숙해 보입니다. 반대로 아주 화려한 기능이 없어도 대응 체계가 보이면 신뢰가 붙습니다. OpenAI API Overview는 운영 환경에서 x-request-id를 로그에 남기라고 권장하고, production best practices는 보안·비용·성능·아키텍처를 함께 보라고 설명합니다. (OpenAI 개발자)

---

먼저 결론부터: B2B 장애 대응에서 꼭 준비해야 할 6가지

제가 추천하는 기본 세트는 이렇습니다.

1. 장애 유형 분류
2. request ID / tenant ID / endpoint 로그
3. 고객 커뮤니케이션 기준
4. 실시간 / background / batch 우회 기준
5. OpenAI 상태 점검 루틴
6. 내부 runbook + 고객 FAQ

이 여섯 가지가 있으면, 적어도 “어떻게 움직일지 모르는 상태”는 벗어납니다.

---

1. 장애는 한 종류가 아닙니다. 먼저 분류부터 해야 합니다

운영하다 보면 모든 장애가 비슷해 보일 때가 있어요.
근데 실제로는 완전히 다릅니다.

대표적인 유형

• 인증/권한 문제: 401, 403
• rate limit 문제: 429
• 일시적 서버/네트워크 문제: 5xx, timeout
• 우리 앱 문제: validation, DB, queue, worker 적체
• 외부 상태 문제: OpenAI 상태 페이지 이슈
• 고객 정책 문제: background 허용 안 되는 고객, store=false 강제 경로 등

OpenAI는 rate limits를 별도 가이드로 설명하고, API Overview에서는 request IDs와 HTTP 에러 해석을 다룹니다. 상태 이상은 status.openai.com에서 현재 및 과거 uptime 정보를 확인할 수 있다고 Help Center가 안내합니다. (OpenAI 플랫폼)

왜 이게 중요하냐면

401을 429처럼 다루면 안 되고,
429를 5xx처럼 다루면 안 됩니다.

이걸 같은 “에러”로만 보면 대응이 늘 늦어집니다.

---

2. request ID는 선택이 아니라 거의 필수입니다

이건 진짜 강조하고 싶습니다.

OpenAI 공식 Python 라이브러리 문서는 모든 응답 객체에 _request_id가 붙고, 이는 x-request-id 헤더에서 온다고 설명합니다. API Overview도 production 환경에서는 request IDs를 로그에 남기라고 권장합니다. support 문의 시에도 request ID가 있으면 훨씬 빨라집니다. (OpenAI 개발자)

즉, 최소한 아래는 같이 남겨야 합니다.

• request_id
• tenant_id
• user_id 또는 actor
• endpoint
• model
• latency_ms
• input_tokens, output_tokens
• error_type

고객이
“어제 3시쯤 응답이 이상했어요”
라고 했을 때,

우리가
“req_abc123 기준으로 추적해보겠습니다”
라고 말할 수 있느냐가 꽤 큰 차이를 만듭니다.

---

3. 공개 SLA를 과장해서 말하면 안 됩니다

이건 B2B 대응에서 정말 조심해야 합니다.

OpenAI Help Center의 “Is there an SLA for latency guarantees...” 문서는 일반적으로 “SLA를 준비 중이며, 특정 latency 요구가 있으면 계정으로 문의하라”고 안내합니다. 반면 Priority processing 문서는 Enterprise customers only 기준으로 99.9% uptime SLA와 latency SLA를 제시하고, 미충족 시 service credits가 제공될 수 있다고 설명합니다. (OpenAI Help Center)

그래서 고객에게는 이렇게 설명하는 편이 안전합니다

• 일반 API 사용: 공개 docs 기준으로는 전 범용 latency SLA를 약속하는 문서를 찾기 어렵고, 상태 페이지와 운영 로그 기준으로 대응
• Enterprise + Priority processing: 문서화된 uptime / latency SLA가 있으며 별도 계약/영업 경로와 연결 가능

이걸 헷갈리면 안 됩니다.
괜히 “OpenAI가 SLA 보장합니다”라고 퉁치면 나중에 설명이 어려워져요.

---

4. 고객 커뮤니케이션은 “사과”보다 “상태 분류”가 먼저입니다

장애 대응에서 많이 놓치는 게 있습니다.
문제가 생기면 바로 장문의 안내문부터 쓰고 싶어져요.

그런데 B2B에서는 보통 이 순서가 더 중요합니다.

1. 이게 우리 문제인가, 외부 상태 문제인가
2. 어느 고객 범위까지 영향이 있는가
3. 실시간만 느린가, background도 영향이 있는가
4. 대체 경로가 있는가
5. 언제 다시 업데이트할 것인가

OpenAI status page는 현재 및 과거 operational 상태를 공개하고 있고, Help Center도 상태 페이지를 먼저 확인하라고 안내합니다. 즉, 고객 공지 전 최소한 OpenAI 측 상태와 우리 서비스 상태를 분리해서 파악해야 합니다. (OpenAI Status)

좋은 공지 예시 구조

• 발생 시각
• 영향 범위
• 현재 상태
• 우회 방법
• 다음 업데이트 시각

이 정도만 있어도 훨씬 안정적으로 보입니다.

---

5. 긴 작업은 장애 시 우회 경로를 따로 가져가는 게 좋습니다

OpenAI background mode는 오래 걸리는 작업을 비동기로 처리하게 해주고, Batch는 대량 비동기 작업을 낮은 비용으로 돌리게 해줍니다. Priority processing은 Enterprise 고객에게 더 예측 가능한 저지연 성능을 제공할 수 있다고 문서화돼 있습니다. (OpenAI 플랫폼)

이걸 운영 관점으로 풀면 이런 기준이 생깁니다.

실시간이 흔들릴 때

• 즉시성 중요한 요청만 남기고
• 긴 리포트/대형 요약은 background로 밀기
• 대량 작업은 batch로 분리
• 특정 Enterprise 고객은 priority processing 검토

즉, 장애 대응은 “고친다”만이 아니라
부하를 다른 경로로 우회시킨다도 포함됩니다.

이 감각이 있으면 서비스가 훨씬 덜 무너집니다.

---

6. Rate limit은 장애 대응 문서에 꼭 들어가야 합니다

반응형

OpenAI rate limits 가이드는 요청/토큰 단위 제한을 설명하고, API Overview는 응답 헤더로 rate limit 관련 값들이 내려온다고 설명합니다. Priority processing 문서도 rate limits는 standard traffic과 공유되고, 급격한 램프업에는 ramp rate limits가 있다고 밝힙니다. (OpenAI 플랫폼)

그래서 runbook에는 최소한 이런 문장이 있어야 합니다.

• 429가 증가하면 즉시 retry만 반복하지 말 것
• burst traffic인지, 배치/백필 작업 때문인지 확인할 것
• 필요 시 batch / flex / background로 우회할 것
• Enterprise 환경이면 priority/scale tier 검토 여부를 기록할 것

이런 기준이 없으면 429가 날 때마다
“OpenAI가 느린가?”
정도로만 보게 됩니다.

---

7. support 문의 템플릿도 미리 준비해두면 좋습니다

OpenAI Support Help Center 문서는 문의 시 가능한 한 자세한 정보와 함께 request ID, timestamp, timezone, 재현 정보 등을 준비하라고 안내합니다. (OpenAI Help Center)

이걸 팀 안에서 템플릿으로 정리해두면 정말 편합니다.

최소 포함 정보

• 발생 시각(타임존 포함)
• endpoint
• tenant/customer
• request_id
• error code / message
• 재현 여부
• status page 확인 결과
• 최근 배포 여부

이건 아주 사소해 보이는데,
막상 장애가 났을 때 엄청 큰 차이를 만듭니다.

---

지금 바로 써볼 수 있는 “장애 분류 + 대응 수준” 코드 예제

아래 코드는 간단하지만,
운영 중 들어온 실패를 severity와 next_action으로 빠르게 분류하는 데 쓸 수 있습니다.

from dataclasses import dataclass
from typing import Literal


Severity = Literal["low", "medium", "high", "critical"]


@dataclass
class IncidentInput:
    error_type: str
    http_status: int | None
    affects_multiple_tenants: bool
    is_openai_status_incident: bool
    repeated_in_last_10m: bool
    endpoint_type: Literal["realtime", "background", "batch"]


@dataclass
class IncidentDecision:
    severity: Severity
    next_action: str
    customer_update_needed: bool


def classify_incident(incident: IncidentInput) -> IncidentDecision:
    if incident.is_openai_status_incident and incident.affects_multiple_tenants:
        return IncidentDecision(
            severity="critical",
            next_action="상태 페이지 확인 후 고객 공지, 실시간 트래픽 축소, background/batch 우회 검토",
            customer_update_needed=True,
        )

    if incident.http_status == 429:
        return IncidentDecision(
            severity="high" if incident.affects_multiple_tenants else "medium",
            next_action="재시도 정책/큐 길이 확인, burst traffic 또는 백필 작업 여부 점검",
            customer_update_needed=incident.affects_multiple_tenants,
        )

    if incident.http_status in {401, 403}:
        return IncidentDecision(
            severity="high",
            next_action="키/권한/프로젝트 설정 확인, 최근 secret 변경 여부 점검",
            customer_update_needed=incident.affects_multiple_tenants,
        )

    if incident.http_status and incident.http_status >= 500:
        return IncidentDecision(
            severity="high" if incident.repeated_in_last_10m else "medium",
            next_action="request_id 확보, status page 확인, 배포 영향 여부 확인",
            customer_update_needed=incident.affects_multiple_tenants,
        )

    if incident.endpoint_type == "background":
        return IncidentDecision(
            severity="low",
            next_action="job backlog와 worker 상태 확인, 즉시 공지보다 내부 복구 우선",
            customer_update_needed=False,
        )

    return IncidentDecision(
        severity="low",
        next_action="개별 로그 확인 후 추세 모니터링",
        customer_update_needed=False,
    )


if __name__ == "__main__":
    example = IncidentInput(
        error_type="RateLimitError",
        http_status=429,
        affects_multiple_tenants=True,
        is_openai_status_incident=False,
        repeated_in_last_10m=True,
        endpoint_type="realtime",
    )

    decision = classify_incident(example)
    print(decision)

실행 방법

python incident_classifier.py

예상 결과

IncidentDecision(
    severity='high',
    next_action='재시도 정책/큐 길이 확인, burst traffic 또는 백필 작업 여부 점검',
    customer_update_needed=True
)

이 코드는 아주 단순하지만,
장애를 무조건 감정적으로만 다루지 않고 분류 기반으로 다루는 습관을 만드는 데 꽤 도움이 됩니다.

---

B2B 장애 대응 체크리스트

운영 로그

• request_id를 남기는가
• tenant_id와 endpoint를 함께 남기는가
• error_type 분류가 되는가

상태 확인

• status.openai.com 확인 루틴이 있는가
• 최근 배포 여부를 바로 볼 수 있는가
• worker / batch / background 상태를 따로 볼 수 있는가

고객 공지

• 영향 범위가 정리되는가
• 우회 경로가 있는가
• 다음 업데이트 시각을 말할 수 있는가

지원 체계

• support 문의용 템플릿이 있는가
• request_id와 timestamp를 바로 뽑을 수 있는가
• enterprise 고객 SLA 문의 시 priority/scale tier 검토 기준이 있는가

---

FAQ

Q. OpenAI API 전체에 공개된 일반 SLA가 있나요?

제가 확인한 공식 Help Center 문서 기준으로는 일반 API 전반에 대한 공개 latency SLA는 “준비 중”이라고 안내합니다. 대신 Enterprise 고객용 Priority processing에는 uptime SLA와 latency SLA가 문서화돼 있습니다. (OpenAI Help Center)

Q. request ID는 꼭 저장해야 하나요?

네. API Overview와 Python 라이브러리 문서 모두 production 환경에서는 request IDs를 로그에 남기라고 권장합니다. support 문의와 원인 추적에 정말 유용합니다. (OpenAI 개발자)

Q. 장애가 나면 고객에게 바로 OpenAI 문제라고 말해도 되나요?

권장하지 않습니다. 먼저 status page, 우리 배포 상태, tenant 영향 범위, queue/worker 상태를 같이 봐야 합니다. OpenAI status page는 공개 상태 확인용으로 유용하지만, 우리 서비스 레이어 문제와 섞여 있을 수 있습니다. (OpenAI Status)

Q. B2B 고객에게 더 강한 성능 보장이 필요하면 어떻게 하나요?

일반 API 사용만으로는 설명이 제한적일 수 있습니다. Enterprise 고객용 Priority processing은 문서상 uptime SLA와 latency SLA가 제공되며, 해당 요구가 있으면 영업/계약 경로와 함께 검토하는 편이 좋습니다. (OpenAI)

---

핵심 요약

• B2B SaaS 운영에서는 기능보다 장애 분류, request ID 로그, 상태 확인, 고객 공지 체계가 먼저입니다. (OpenAI 개발자)
• 일반 API 전체에 대한 공개 latency SLA는 준비 중이라는 공식 Help Center 안내가 있고, Enterprise용 Priority processing에는 문서화된 SLA가 있습니다. (OpenAI Help Center)
• rate limit, background, batch, priority/standard 경로를 분리해서 보는 runbook이 필요합니다. (OpenAI 플랫폼)
• support 문의에는 request_id, timestamp, 재현 정보가 핵심입니다. (OpenAI Help Center)

---

출처

• OpenAI API Overview — request IDs와 rate limit 헤더, 운영 시 로깅 권장 사항. (OpenAI 개발자)
• OpenAI Python API library — _request_id 제공 설명. (OpenAI 개발자)
• OpenAI Rate limits guide — 요청/토큰 제한 가이드. (OpenAI 플랫폼)
• OpenAI Background mode guide — 긴 작업의 비동기 처리 방식. (OpenAI 플랫폼)
• OpenAI Batch API guide — 대량 비동기 처리와 비용 절감. (OpenAI 개발자)
• OpenAI Status page — 현재 및 과거 운영 상태 확인. (OpenAI Status)
• OpenAI Help Center: Is there an SLA for latency guarantees... — 일반 API SLA 관련 공식 안내. (OpenAI Help Center)
• OpenAI Priority Processing for API Customers — Enterprise 고객용 uptime/latency SLA 및 service tier 설명. (OpenAI)
• OpenAI Help Center: How can I contact support? — support 문의 시 준비 정보. (OpenAI Help Center)

Python, OpenAI, FastAPI, B2B SaaS, 장애 대응, SLA, request id, OpenAI Status, Rate Limits, Background mode, Batch API, Priority Processing, 운영 runbook, AI 백엔드 운영, 주니어 개발자