AI API Fallback 전략: Provider 장애 매트릭스 구축
Failure Class, Response Phase, Idempotency와 Attempt Budget에 따라 Retry, Same-contract Fallback 또는 중단을 결정합니다.
AI API Retry, Route Fallback, Model Substitution은 서로 다른 동작입니다. Retry는 같은 계약에서 Attempt를 반복합니다. Route Fallback은 요청된 Model과 Protocol을 다른 적격 Channel 또는 Group으로 보냅니다. Model Substitution은 요청 모델을 바꾸므로 품질, 가격, 지연, Tool 동작, Context Limit, Output Format까지 달라질 수 있습니다.
신뢰할 수 있는 정책은 장애가 난 뒤 즉석에서 결정하지 않습니다. Failure Class, 응답이 이미 전달됐는지, 전체 업무 동작이 Idempotent한지, 사용자 Deadline 안에 몇 번의 Attempt가 가능한지를 사전에 정의합니다.
Retry, Fallback, Model Substitution 구분하기
Configuration, Log, Runbook에서 세 동작을 다른 이름으로 기록합니다.
| 동작 | 바뀌는 항목 | 적절한 목적 | 주요 위험 |
|---|---|---|---|
| Same-route Retry | 시간과 Attempt Number | 같은 Route의 짧은 일시 장애 복구 | 비정상 Dependency에 부하 반복 |
| Same-contract Fallback | Upstream Channel, Account 또는 순서가 있는 Group | 한 경로가 실패해도 Model과 Protocol 유지 | 동일하다고 가정한 Route 사이의 숨은 비호환 |
| Model Substitution | Model ID 또는 명시적 Model Policy | 제품이 승인한 품질·비용·가용성 절충 | 동작과 Billing의 조용한 변경 |
세 동작을 모두 “Retry”라고 부르면 안 됩니다. 운영자는 요청이 다시 실행됐는지, 다른 경로로 이동했는지, 다른 모델이 답했는지 알아야 합니다. 사용자의 관점에서도 Model Substitution은 명시적 Product Contract여야 하며 보이지 않는 복구 수단이 되어서는 안 됩니다.
일부 Gateway는 Provider 또는 Model Step 순서를 지원합니다. Cloudflare Fallback 문서처럼 성공한 Step을 드러낼 수도 있습니다. 특정 Vendor 정책을 복제하는 것보다 중요한 원칙은 Route가 바뀔 때마다 Attempt-level Evidence를 남기는 것입니다.
Request 재실행 전 네 가지 Gate 적용하기
Status Code 하나만으로 Retry Policy를 결정할 수 없습니다.
- Failure Class: 일시적, 영구적, Caller 원인, 완료 여부가 불명확한 실패 중 무엇인가?
- Response Phase: Header 전, Effective Output 전, Output 전달 후 중 언제 발생했는가?
- Idempotency: 전체 Application Operation을 반복해도 Side Effect가 중복되지 않는가?
- Attempt Budget: 남은 Wall-clock Time과 사용 가능한 Attempt가 있는가?
Google Cloud Retry Strategy도 일반 API에서 같은 두 기준을 강조합니다. 응답이 Retry 가능성을 보여 주는지, Idempotency가 Replay 안전성을 보장하는지 판단해야 합니다. 408, 429, 5xx, Socket Timeout, Disconnect는 흔히 일시적이지만 Non-idempotent Operation에는 더 엄격한 조건이 필요합니다.
AI Workflow의 Idempotency는 Model HTTP Request 밖까지 이어집니다. Prompt를 다시 보내면 이메일, 환불, 배포, Database Write를 다시 제안할 수 있습니다. Inference가 Read-only여도 Tool Execution에는 Stable Idempotency Key와 Persisted Result가 필요합니다.
Failure Matrix에서 정책 시작하기
아래는 보수적인 Application Policy입니다. Gateway가 Terminal Result를 전달하기 전에 내부 Same-contract Channel Failover를 수행할 수 있으므로 두 계층이 같은 실패를 중복 재시도하지 않도록 조정해야 합니다.
| 실패 또는 단계 | Same-route Retry | Same-contract Fallback | 중단 또는 조사 | 이유 |
|---|---|---|---|---|
| Client Validation Error, Unsupported Field, Malformed Request | 아니요 | 아니요 | Request 수정 | 같은 잘못된 계약을 반복해도 성공하지 않음 |
| Gateway Authentication, Authorization, Quota, Policy Denial | 아니요 | 아니요 | Account 또는 Policy 수정 | 다른 Provider Route로 Gateway 결정을 우회하면 안 됨 |
| Output 전 Upstream Credential 또는 Account Failure | 실패 Route에서는 아니요 | 검증된 적격 Channel이 있으면 가능 | Channel 격리 및 조사 | 사용자 계약을 유지하며 비정상 Credential 제거 가능 |
Output 전 Network Failure 또는 408 |
Idempotent한 경우 최대 한 번의 제한된 Attempt | 가능 | Deadline에서 중단 | 일시적일 수 있지만 Disconnect 뒤 완료 여부는 모호함 |
Output 전 429 |
Retry-After를 지키는 지연 Retry |
다른 Same-contract Route에 용량이 있으면 가능 | Budget 소진 시 중단 | 즉시 반복하면 Rate Limit을 악화함 |
Output 전 500, 502, 503, 504 |
Backoff가 있는 제한된 Retry | 가능 | 반복되는 Route 장애 조사 | 흔히 일시적이지만 모든 Route가 안전하다는 증거는 아님 |
| Downstream Output 전 Schema-invalid Provider Response | 대체로 아니요 | 같은 Schema를 검증한 Route만 가능 | Compatibility 조사 또는 격리 | 비호환 구현을 반복해도 개선되기 어려움 |
| Model Refusal 또는 Policy-safe Completion | 아니요 | 아니요 | 모델 결과 반환 | 정상적인 Refusal은 인프라 장애가 아님 |
Caller Cancellation 또는 Downstream 499 |
아니요 | 아니요 | 즉시 중단 | Caller가 더 이상 작업을 원하지 않음 |
| Visible Content 또는 Tool Arguments 전달 후 Partial Stream | Transparent Replay 금지 | Transparent Fallback 금지 | Partial 표시 후 Application이 결정 | 새 Stream이 기존 Output을 반복하거나 모순될 수 있음 |
| Tool Side Effect 완료 여부 불명 | Reconcile 전 금지 | Reconcile 전 금지 | Idempotency Record 또는 외부 시스템 조회 | Re-inference가 같은 Side Effect를 재제안할 수 있음 |
503이 Output 전에 도착한 경우와 400개의 Text Token이 렌더링된 뒤 연결이 끊긴 경우는 같은 실패가 아닙니다.
Stream 시작을 Commit Boundary로 취급하기
Downstream Output이 시작되기 전에는 Gateway가 실패한 Attempt를 버리고 다른 Route를 시도해도 Caller에게 두 답을 노출하지 않을 수 있습니다. 의미 있는 첫 Byte가 전달된 뒤에는 Transparent Replay가 안전하지 않습니다.
Stream을 다시 시작하면 다음 문제가 생길 수 있습니다.
- 답변 시작 부분 중복
- 서로 다른 후속 내용 생성
- 새 Call ID를 가진 중복 Function Call
- 경계가 불명확한 Usage와 Cost 증가
- Client가 Event의 Attempt를 식별하지 못함
Output 이후 Stream이 끊기면 원래 Request Identity와 함께 Terminal Partial 또는 Transport Error를 반환합니다. Application은 명시적인 “다시 시도”, 안전한 Checkpoint에서 계속하기, Partial Output 폐기를 제공할 수 있습니다. 새 Model Stream을 기존 Stream에 몰래 이어 붙이면 안 됩니다.
Function Calling은 더 엄격합니다. Retry가 Tool Call을 재생성하기 전에 이미 수락한 Tool Call Identity와 Side-effect Result를 저장해야 합니다. Function Calling 비교에서 Call ID와 Application Idempotency의 관계를 확인할 수 있습니다.
Attempt와 Wall-clock Time으로 Backoff 제한하기
Exponential Backoff는 반복 Attempt를 시간상 분산하고 Jitter는 공통 장애 뒤 많은 Client가 동시에 재시도하는 현상을 막습니다.
delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)
유효한 Retry-After가 사용자 Deadline 안에 들어오면 따릅니다. Backoff는 Retry 허가가 아니므로 Failure와 Idempotency Gate를 먼저 통과해야 합니다.
Retry Count만이 아니라 Total Budget을 정의합니다.
- 한 User Action의 최대 Attempt
- Queue와 Backoff를 포함한 최대 Elapsed Time
- Fallback Group 선택 전후의 Attempt 상한
- 유용한 답을 만들기 위해 남겨 둘 최소 시간
- Caller Cancellation을 모든 Active Attempt에 전달하는 규칙
Deadline이 15초인 Interactive Request에 10초짜리 Attempt 세 번을 배정하는 것은 실현 가능한 정책이 아닙니다. Batch Workload는 더 긴 Budget을 사용할 수 있지만 Terminal Deadline과 Durable Job Identity가 필요합니다.
계층 간 Retry Amplification 막기
SDK가 3번, Gateway가 각 요청마다 3개 Route, Upstream Proxy가 각 Route마다 2번 호출한다고 가정합니다.
3 client attempts × 3 gateway attempts × 2 upstream attempts = 18 provider calls
한 User Action이 18개의 Provider Call로 늘어납니다. 장애 중에는 Queue, Rate Limit, 비용, 복구 시간이 모두 악화됩니다.
Retry Ownership을 명시적으로 나눕니다.
- Gateway는 즉시 Same-contract Channel Failover를 담당합니다.
- Application은 전체 User Action을 반복할 수 있는지 결정합니다.
- Gateway가 Retry하면 SDK Automatic Retry는 끄거나 엄격히 제한합니다.
- Async Job은 하나의 Durable Job ID와 Attempt Ledger를 사용합니다.
- Caller Cancellation 뒤에는 어떤 계층도 새 Attempt를 시작하지 않습니다.
각 계층의 Attempt Number와 Stable End-to-end Request ID를 함께 기록해야 합니다. 그렇지 않으면 각 계층은 두세 번만 시도한 것처럼 보이고 전체 증폭은 숨겨집니다.
Fallback이 계약을 보존하는지 검증하기
공개 Model Name이 같아도 Route 동작이 같다는 뜻은 아닙니다. Same-contract Fallback Set에 Channel을 추가하기 전에 다음 증거가 필요합니다.
| 계약 영역 | 필요한 증거 |
|---|---|
| Model Identity | Requested Model을 Silent Mapping 없이 사용 |
| Endpoint | 설정된 Responses 또는 Chat Completions Request 수용 |
| Streaming | Event Type, Termination, Usage, Cancellation 처리 |
| Structured Output | 필요한 JSON Schema Subset과 Strict Behavior 동작 |
| Function Calling | Tool Definition, Call ID, Argument Streaming, Result Round-trip |
| Limits | Context, Output, Rate, Concurrency가 Workload에 적합 |
| Errors | Secret 노출 없이 Status와 Error Body 분류 가능 |
| Usage and Cost | Token, Cache Field, Service Tier, Price Policy 정의 |
| Safety and Region | 필요한 Policy, Data Path, Residency 유지 |
필수 영역 하나라도 실패하면 해당 Route는 그 Workload의 Transparent Fallback이 아닙니다. 별도의 명시적 Product Policy에서는 사용할 수 있습니다.
다른 모델로 변경하는 것은 항상 Product Decision입니다. 허용 Model, Quality Floor, Price Ceiling, Tool Contract, User-visible Disclosure를 정의해야 하며 Route Error만으로 더 저렴하거나 약한 모델을 조용히 사용하면 안 됩니다.
Modelflare의 현재 Fallback Semantics 이해하기
Modelflare는 API Client가 요청한 모델에 맞는 적격 경로를 찾습니다. 일반 API Key에는 Primary Group과 순서가 있는 Fallback Group 목록을 둘 수 있습니다. Smart API Key는 Routing Strategy에 따라 Account가 사용할 수 있는 Group을 평가합니다. 두 방식 모두 Requested Model을 다른 모델로 조용히 바꾸지 않습니다.
Group-level RPM Admission은 Billing과 Upstream Request 전에 수행됩니다. 선택한 Group이 가득 차면 Ordered Fallback Group 또는 Smart Routing Candidate를 평가하고, 적격 Group이 없으면 429를 반환합니다.
Group 안에서는 Channel Priority가 Account Failover 순서를 결정합니다. Upstream Error 뒤 실패 Channel을 제외하고 나머지 적격 Channel을 선택합니다. 현재 Channel Failover는 RetryTimes나 AutomaticRetryStatusCodes와 독립적이며 성공, Route 소진, Caller Cancellation, 또는 Downstream Response가 시작돼 Transparent Replay가 불가능할 때 중단됩니다.
이는 내부 Same-model Path Decision이지 Client가 무제한 Retry Loop를 추가해도 된다는 뜻이 아닙니다. Group 및 Channel 설계는 Reliable AI API Routing, Gateway Policy Error와 Upstream Failure 구분은 AI API Error Troubleshooting을 참고하세요.
모든 Attempt의 Evidence 보존하기
최종 200은 첫 Route가 성공했다는 증거가 아니며 Final Channel ID도 실패한 Attempt를 설명하지 못합니다. 최소한 다음을 보존합니다.
- Stable Request ID와 Caller-visible Correlation ID
- Attempt Sequence와 Group/Channel Reference
- Attempt별 Model과 Endpoint Contract
- Failure Status, Error Class, Stream Phase
- Downstream Output 시작 여부
- Timing Milestone과 Cancellation State
- 가능한 경우 Input, Output, Cached-token Usage
- Completed 또는 Billable Attempt별 Cost Attribution
- Success, Exhausted, Cancelled, Partial, Policy Stop 중 Terminal Reason
Fallback 진단만을 위해 API Key, Raw Prompt, Raw Response, Provider Credential을 저장하지 마세요. Redacted Error Class와 Timing Metadata로 충분한 경우가 많습니다. Request Archive는 명시적으로 활성화한 장애 조사에만 제한적이고 짧게 보관합니다.
Production Traffic 전에 정책 훈련하기
실제 Protocol Boundary와 안전하고 결정적인 Input으로 Staging Exercise를 수행합니다.
- Header 전에 Primary Channel을 비활성화하고 다음 Same-model Path를 확인합니다.
- Rate Limit을 반환해 Attempt Limit과
Retry-After를 확인합니다. - Caller를 취소하고 이후 Attempt가 시작되지 않음을 증명합니다.
- Output 뒤 Stream을 끊고 Transparent Replay가 없음을 확인합니다.
- Invalid Request를 보내 Fallback이 오류를 숨기지 않는지 확인합니다.
- Tool Workflow를 반복해 Side Effect가 하나만 기록되는지 확인합니다.
- 모든 Route를 소진해 명확한 Terminal Error 하나를 확인합니다.
- Attempt Ledger를 점검하고 Usage와 Cost를 Reconcile합니다.
작은 Workload부터 적용하고 Attempt Count, Success-after-fallback, Raw Success Rate를 따로 모니터링합니다. 비정상 Route를 빠르게 제거할 수 있어야 합니다. 목표는 Fallback 횟수를 늘리는 것이 아니라 원래 Model Contract를 보존하면서 제한된 Deadline 안에서 안전하게 복구하고 모든 Attempt의 증거를 남기는 것입니다.