작성자 주: 오류 코드별로 모델 API 오류를 분류해 언제 재시도하고, 언제 예비 모델로 전환하며, 언제 멈추고 설정을 수정해야 하는지 설명해요. 오류 코드 분류표, 예비 모델 확인표, 출시 전 점검 목록도 함께 제공합니다.
모델 API에서 오류가 발생하면 먼저 오류 유형을 확인한 뒤 대응 방법을 결정하세요. 4xx는 대부분 요청이나 설정 문제이므로 재시도해도 해결되지 않아요. 5xx, 529, 타임아웃은 횟수를 제한해 재시도하고, 그래도 실패하면 예비 모델로 전환할 수 있어요. 멱등성이 보장되지 않는 요청은 자동으로 재시도하지 마세요. 재시도가 기본 대응은 아니며, 모델 전환으로 모든 문제가 해결되는 것도 아니에요. 실제 운영 장애 중에는 모델 자체의 문제가 아니라 오류 처리 로직이 작은 장애를 중복 과금, 중복 DB 쓰기, 전체 체인의 요청 제한으로 키운 사례도 많아요.
이 글은 오류 코드 사전을 번역한 글이 아니에요. 모델 API를 운영 또는 준운영 환경에 연동한 개발자를 위해, 오류가 발생했을 때 상황을 악화시키지 않는 방법에 집중해요. 오류 코드 분류표, 재시도 및 대체 전략, 예비 모델 기능 확인표, 바로 활용할 수 있는 출시 전 점검 목록을 살펴볼 거예요. 핵심은 한 문장으로 정리할 수 있어요. 4xx는 먼저 수정하고, 5xx는 재시도를 고려하며, 멱등성이 없는 요청은 일단 멈추세요.
모델 API 오류 분류: 5가지 유형별 재시도와 전환 방법
결론부터 말하면, 모델 API 오류는 다섯 가지로 나눌 수 있고 유형별 대응 방향도 대체로 정해져 있어요. 오류 코드를 먼저 분류하면 재시도나 전환 여부를 판단하기가 쉬워져요.
| 오류 유형 | 대표 상태 코드 | 원인 위치 | 기본 조치 |
|---|---|---|---|
| 요청 오류 | 400, 404, 409, 422 |
요청 본문, 파라미터, 모델 ID, 엔드포인트 | 재시도하지 않고 요청 수정 |
| 인증·권한 오류 | 401, 403 |
키, 요청 헤더, 권한, 지역 또는 정책 | 재시도하지 않고 키와 권한 확인 |
| 할당량 또는 속도 제한 | 402, 429 |
잔액, 동시 요청 수, 요청 속도, 모델 할당량 | 402는 중단, 429는 오류 본문을 확인한 뒤 대기 후 재시도하거나 전환 |
| 업스트림 장애 | 500, 502, 503, 529 |
게이트웨이, 업스트림 서비스, 과부하 | 횟수를 제한해 재시도하고 실패하면 전환 |
| 타임아웃 또는 스트림 중단 | 408, 504, 네트워크 타임아웃, 스트림 연결 끊김 |
네트워크 경로, 긴 출력, 느린 업스트림 응답 | 실행 또는 과금 여부를 먼저 확인하고 멱등성이 보장될 때만 재시도 |
5가지 오류 분류의 핵심: ‘재시도’와 ‘전환’ 구분하기
재시도는 같은 모델과 같은 경로로 요청을 다시 보내는 것으로, 일시적인 장애를 해결하는 데 적합해요. 전환은 모델이나 경로를 바꾸는 것으로, 특정 업스트림을 계속 사용할 수 없을 때 적합해요. 두 방식의 비용도 달라요. 재시도하면 지연이 생기고 중복 과금될 수 있으며, 전환하면 출력 품질과 도구 호출 호환성, 비용이 달라질 수 있어요.
따라서 오류 대응은 세 단계로 진행해요. 먼저 오류 유형을 확인하고, 요청의 멱등성을 판단한 다음, 재시도·전환·중단 중 하나를 선택하세요. 두 번째 단계를 건너뛰는 것이 가장 위험해요. 이미 실행된 도구 호출을 다시 실행하면 단순히 비용이 더 드는 것 이상의 문제가 생길 수 있기 때문이에요.
“모두 재시도”하면 모델 API 오류가 더 심해지는 이유
결론부터 말하면, 모든 오류를 무조건 재시도하는 방식은 안전해 보이지만 실제로는 비용, 부작용, 요청 제한을 동시에 키워요. 운영 환경에서는 이런 로직 때문에 생긴 장애가 원래 오류보다 추적하기 어려운 경우가 많아요.
첫 번째 문제는 중복 과금이에요. 스트리밍 응답이 중단됐다고 해서 요청이 반드시 실패한 것은 아니에요. 상위 서비스에서 이미 일부 토큰을 생성해 비용이 발생했을 수 있죠. 무작정 요청을 다시 보내면 같은 작업에 두 번 비용을 지불하는 셈이에요. 특히 출력이 긴 작업에서 두드러져요.
두 번째 문제는 중복 실행이에요. 에이전트 환경에서는 한 번의 모델 요청으로 데이터베이스에 쓰기, 메시지 발송, 작업 생성, 심지어 결제까지 이뤄질 수 있어요. 도구 호출 단계에서 타임아웃이 발생하면 도구가 이미 실행됐는지 알 수 없어요. 이때 요청 전체를 그대로 다시 보내면 주문이 두 건 생성되거나 이메일이 두 통 발송될 수 있어요.
세 번째 문제는 요청 제한이 더 심해진다는 점이에요. 429는 상위 서비스가 “속도를 늦춰 달라”고 알려주는 신호예요. 이때 클라이언트가 즉시 동시 재시도를 하면 오히려 부하를 더하는 셈이죠. 더 흔한 실수는 모든 4xx 오류를 재시도하는 것이에요. 401은 원래 키를 잘못 입력해 발생했는데, 몇 차례 재시도하면서 요청량이 한도에 도달할 수 있어요. 결국 로그에는 429만 잔뜩 남아 진짜 원인이 가려져요.
401, 429, 500, 529 오류 코드 분류표: 재시도와 전환이 필요한 경우
결론: 아래 표는 운영 환경에서 자주 발생하는 상태 코드 14가지를 다뤄요. 이 중 재시도할 만한 경우는 일부에 불과하며, 전환은 재시도가 효과 없다고 확인된 뒤에 고려하세요. 표의 ‘전환 여부’는 예비 모델이나 회선으로 바꾸는 것을 뜻해요. 구체적인 의미는 실제 오류 응답 본문과 각 서비스의 문서를 확인하세요.
| 상태 코드 | 일반적인 의미 | 재시도 여부 | 전환 여부 | 조치 |
|---|---|---|---|---|
400 |
요청 형식 또는 매개변수 오류 | 아니요 | 아니요 | 요청 본문을 수정하고 필드와 타입 확인 |
401 |
API 키가 유효하지 않거나 인증 실패 | 아니요 | 아니요 | API 키, Authorization 요청 헤더, Base URL 확인 |
402 |
잔액 부족 또는 할당량 소진 | 아니요 | 상황에 따라 회선 전환 | 충전하거나 할당량이 남은 회선으로 전환하고 알림 발생 |
403 |
권한, 지역 또는 정책에 따른 거부 | 아니요 | 아니요 | 계정 권한, 모델 사용 권한, 지역 제한 확인 |
404 |
모델 또는 엔드포인트가 존재하지 않음 | 아니요 | 아니요 | 모델 ID와 엔드포인트 경로 확인 |
408 |
요청 시간 초과 | 멱등성이 보장될 때 제한적으로 재시도 | 선택 가능 | 실행되지 않았음을 확인한 뒤 1회 재시도 |
409 |
충돌 또는 상태 불일치 | 아니요 | 아니요 | 비즈니스 상태를 확인하고 동시 쓰기 방지 |
422 |
매개변수 유효성 검사 실패 | 아니요 | 아니요 | 매개변수 수정, 구조화 출력의 schema에서 자주 발생 |
429 |
속도 제한, 동시 요청 제한 또는 할당량 문제 | 백오프 후 재시도 | 재시도 실패 시 전환 가능 | 먼저 오류 응답 본문과 Retry-After 확인 |
500 |
업스트림 내부 오류 | 제한적으로 재시도 | 연속 실패 시 전환 | request id와 오류 응답 본문 기록 |
502 |
게이트웨이 오류 | 제한적으로 재시도 | 전환 가능 | 게이트웨이 문제와 업스트림 문제 구분 |
503 |
서비스 사용 불가 | 제한적으로 재시도 | 전환 가능 | Retry-After를 따르고 필요하면 기능 축소 |
504 |
게이트웨이 시간 초과 | 멱등성이 보장될 때만 재시도 | 전환 가능 | 작업이 이미 실행됐는지 먼저 확인 |
529 |
업스트림 과부하 | 제한적으로 재시도 | 전환 가능 | 백오프에 지터를 적용하고, 과부하가 지속되면 전환 |
429가 반드시 속도 제한은 아니에요: 오류 응답 본문을 확인하세요
429는 가장 오판하기 쉬운 코드예요. 속도 제한뿐 아니라 동시 요청 한도 초과, 모델 할당량 소진을 뜻할 수 있고, 드물게는 잔액과 관련되기도 해요. 속도 제한은 보통 몇 초간 백오프하면 복구되지만, 할당량이 소진됐다면 아무리 재시도해도 소용없어요. 가장 비싼 모델로 바로 전환하면 문제는 그대로인데 비용만 두 배로 늘 수 있어요.
429는 다음 순서로 처리하세요.
- 응답 헤더에
Retry-After가 있으면 해당 시간만큼 기다려요. - 오류 응답 본문의 오류 유형 필드를 읽고 rate limit, concurrency, quota를 구분해요.
- 속도나 동시 요청 문제라면 백오프 후 1~2회 재시도하고, 로컬 동시 요청 수도 줄여요.
- 할당량 문제라면 재시도를 중단하고, 알림을 발생시킨 뒤 할당량이 남은 회선으로 전환해요.
500도 비슷하게 접근하면 돼요. 반드시 모델 자체의 문제라는 뜻은 아니며, 게이트웨이나 업스트림에서 발생했을 수도 있어요. 원인 조사와 사용 내역 대조에 필요하므로 request id와 오류 응답 본문 요약을 먼저 기록해 두세요.
모델 API 오류 재시도 전략: 횟수, 백오프, Retry-After와 멱등성
결론부터 말하면, 일시적인 오류만 1~2회 재시도하고, 반드시 지수 백오프와 무작위 지터를 적용해야 해요. 자동 재시도는 멱등 요청에만 허용하세요. 이 네 가지 조건 중 하나라도 충족하지 못하면 자동으로 재시도하지 마세요.
| 항목 | 권장 값 | 설명 |
|---|---|---|
| 재시도 가능한 오류 | 429, 500, 502, 503, 504, 529, 네트워크 타임아웃 |
4xx 중에서는 408과 429만 예외 |
| 최대 재시도 횟수 | 1~2회 | 초과하면 전환 또는 알림 처리하고, 같은 요청을 반복하지 않음 |
| 백오프 간격 | 1s, 2s, 4s로 지수 증가 | 매번 무작위 지터를 추가해 여러 인스턴스가 동시에 재시도하지 않도록 함 |
| Retry-After | 있으면 우선 준수 | 로컬 백오프 알고리즘보다 우선 |
| 멱등성 전제 | 반드시 충족 | 쓰기 작업, 도구 호출, 메시지 발송, 결제는 기본적으로 자동 재시도하지 않음 |
재시도 전략 적용 단계
- 오류 분류 함수를 만드세요. 상태 코드와 오류 본문을 입력받아 다섯 가지 유형 중 하나를 반환하도록 해요. 나머지 로직은 이 분류 결과를 기준으로 처리하고, 비즈니스 코드 곳곳에서 숫자를 직접 판단하지 마세요.
- 요청에 멱등 여부를 표시하세요. 순수 텍스트 생성, 요약, 번역은 보통 멱등 요청으로 볼 수 있어요. 도구를 실행하거나 외부 쓰기 작업을 일으키는 요청은 비멱등으로 표시하세요.
- 비멱등 요청은 먼저 상태를 확인하세요. 도구 호출이 타임아웃되면 작업 또는 데이터베이스 상태를 조회해 실행되지 않았음을 확인한 뒤 재시도하세요. 필요하면 비즈니스 측 멱등성 키로 중복을 방지하세요.
- 총 소요 시간에 상한을 설정하세요. 요청별 재시도 총시간을 제한하지 않으면 사용자 요청은 이미 타임아웃됐는데 백그라운드에서는 계속 재시도할 수 있어요.
- 각 시도를 기록하세요. 최소한 request id, 모델 ID, 상태 코드, 오류 유형, 지연 시간, 토큰 사용량, 재시도 횟수를 기록하세요.
마지막 단계는 자주 생략되지만, 사용량 대조와 오류 해결에 꼭 필요해요. APIYI apiyi.com을 통해 접속한다면 콘솔에서 Key별 사용량과 호출 로그를 확인할 수 있어요. 로컬에 기록한 request id를 플랫폼의 오류 정보와 대조하면 게이트웨이, 업스트림, 자체 요청 본문 중 어디에서 실패했는지 판단할 수 있어요.
스트림 중단은 별도로 처리하세요. 스트리밍 요청이 끊기면 이미 받은 토큰 수와 콘텐츠의 사용 가능 여부를 확인한 뒤 이어서 생성할지, 폐기할지, 요청을 다시 보낼지 결정하세요. 긴 출력 작업을 다시 요청하기 전에는 이전 생성분에도 요금이 부과됐을 수 있다는 점을 고려하세요.
🎯 오류 해결 팁:
500,529처럼 원인을 판단하기 어려운 오류가 발생하면 먼저 오류 본문 원문과 request id를 저장하세요. 그런 다음 APIYI apiyi.com 콘솔에서 같은 시간대의 사용량과 로그를 확인하세요. 상태 코드만 보고 결론 내리지 마세요.
대체 모델 전환 전략: 성능 등급, 모델 매핑 및 호환성 확인
결론부터 말하면, 대체 모델이 동일한 작업을 처리할 수 있는지 미리 확인해야 해요. 장애가 발생한 뒤 처음으로 폴백 경로를 실행하면 두 번째 장애가 발생할 가능성이 높아요.
먼저 모델을 플래그십, 범용, 경량으로 구분하세요. 각 작업 유형에는 기본 모델 하나와 같은 등급이나 인접 등급의 대체 모델 하나를 매핑해요. 모든 요청을 가장 비싼 모델로 폴백하지는 마세요. 업스트림에서 한 번만 장애가 발생해도 비용을 감당하기 어려워질 수 있고, 간단한 작업은 플래그십 모델로 바꿔도 이점이 없는 경우가 많아요.
| 성능 항목 | 기본 모델 | 대체 모델 | 호환 여부 | 전환 전 확인 사항 |
|---|---|---|---|---|
| 컨텍스트 윈도우 | 실제 상한 입력 | 실제 상한 입력 | 확인 필요 | 실제 최대 길이의 입력을 수용할 수 있는지 확인하고, 불가능하면 먼저 입력 잘라내기 전략 수립 |
| 도구 호출 | 도구 schema, 병렬 호출 | 동일 | 확인 필요 | 호출 ID 반환 형식과 인수 구조 검증 |
| 구조화된 출력 | JSON schema 또는 엄격한 JSON | 동일 | 확인 필요 | 동일한 schema로 성공률을 테스트해 422 방지 |
| 멀티모달 입력 | 이미지, 오디오, 비디오 | 동일 | 확인 필요 | 입력 형식과 크기 제한 확인 |
| reasoning 파라미터 | 추론 단계 또는 사고 관련 필드 | 동일 | 확인 필요 | 지원하지 않는 파라미터는 전환 시 제거하거나 매핑 |
| 가격 및 요청 제한 | 콘솔 기준 | 콘솔 기준 | 확인 필요 | 전환 후 비용을 추정하고 할당량이 충분한지 확인 |
| 지역 및 규정 준수 | 허용 범위 | 허용 범위 | 확인 필요 | 대체 경로가 서비스에서 허용하는 지역 및 규정 준수 범위에 속하는지 확인 |
이 표는 작업 유형마다 하나씩 작성하고, ‘호환 여부’에는 검증한 결과만 입력하세요. 특히 reasoning 파라미터는 문제가 생기기 쉬워요. 기본 모델이 지원하는 추론 단계 필드를 대체 모델에 그대로 보내면 400 또는 422가 반환될 수 있어요. 따라서 전환 로직에는 파라미터를 그대로 전달하는 대신 모델에 맞게 조정하는 계층이 필요해요.
모델 매핑: 모델 ID는 콘솔 기준
전환할 때 흔히 발생하는 실수는 모델 ID를 잘못 입력해 404가 반환되는 경우예요. ‘논리 모델명과 실제 모델 ID’의 매핑 테이블을 관리하고, 비즈니스 코드에서는 논리 이름만 참조하는 것이 좋아요. APIYI apiyi.com을 통해 호출할 때 정확한 모델 ID, 사용 가능 상태, 가격은 콘솔과 문서를 기준으로 확인하세요. 연동 시에는 https://api.apiyi.com/v1을 base_url로 통일해 사용해요. 매핑 테이블을 변경한 뒤에는 카나리 요청을 한 번 실행하고 배포하세요.
대체 모델 검증과 멀티 모델 게이트웨이: 카나리, 로그, 자동 폴백
결론부터 말하면, 대체 모델은 운영에 투입하기 전에 실제 업무로 검증해야 해요. 폴백 후에도 상태 코드가 200인지 확인하는 데 그치지 말고 출력 결과를 검증해야 해요. 멀티 모델 게이트웨이는 전환 비용을 줄여주지만, 품질 검증까지 대신해 주지는 않아요.
대체 모델 검증 3단계
- 카나리 요청. 실제 업무 작업을 몇 가지 골라 동일한 프롬프트, 도구, 입력을 주 모델과 대체 모델에 각각 보내세요.
- 동일 작업 비교. 통과율, 지연 시간, 첫 토큰 응답 시간, 토큰 비용, 실패율을 비교하세요. 도구 호출이 필요한 작업이라면 호출 ID, 파라미터 구조, 반환 구조가 호환되는지도 항목별로 확인해야 해요.
- 폴백 후 검증. 실제 전환이 발생한 후에는 JSON 파싱 가능 여부, 필수 필드 누락 여부, 도구 파라미터의 유효성 등을 자동으로 확인하고, 전환 이유와 검증 결과를 기록하세요.
폴백 경로는 정기적으로 훈련해야 해요. 매주 일부 트래픽을 의도적으로 대체 모델에 전환해 경로가 여전히 작동하는지 확인하세요. 의존성, 파라미터, 모델 ID가 모르는 사이에 작동하지 않게 되는 상황을 막을 수 있어요.
로그에는 최소한 다음 필드를 포함하는 것이 좋아요.
- 요청 ID, 모델 ID, 엔드포인트, 상태 코드, 오류 유형, 오류 본문 요약
- 지연 시간, 첫 토큰 응답 시간, 총 소요 시간, 재시도 횟수, 전환 대상
- 입력 토큰, 출력 토큰, 캐시 히트 여부, 예상 비용
- 도구 호출 이름, 호출 ID, 실행 성공 여부
- 전환 이유, 전환 후 검증 통과 여부
재해 복구에서 멀티 모델 게이트웨이의 역할
여러 공급업체를 직접 연동해 재해 복구 체계를 구축하려면 여러 세트의 키, SDK, 오류 형식을 관리해야 해요. APIYI apiyi.com 같은 통합 게이트웨이를 사용하면 키 하나로 OpenAI, Claude, Gemini, DeepSeek, Qwen 등 주요 모델을 호출할 수 있어요. 인터페이스는 OpenAI 표준과 호환되며 Claude와 Gemini의 네이티브 형식도 지원해요. 주 모델과 대체 모델을 동일한 연동 코드에 구성할 수 있으므로, 전환할 때 전체 통합 경로가 아닌 모델 ID만 변경하면 돼요.
플랫폼은 다중 노드 배포, 지능형 라우팅, 자동 폴백, 로드 밸런싱도 제공해 상위 서비스의 일시적인 불안정을 일부 흡수할 수 있어요. 다만 게이트웨이 계층의 자동 폴백이 비즈니스 계층의 판단을 대신할 수는 없어요. 멱등성 검사, 도구 호출 중복 제거, 출력 검증은 여전히 자체 코드에서 처리해야 해요. 게이트웨이는 경로와 노드의 가용성을, 애플리케이션은 작업의 정확성을 책임지는 방식이 안전해요.
💡 재해 복구 팁: 주 모델과 대체 모델을 설계할 때 APIYI apiyi.com에서 동일한 키로 두 모델에 같은 카나리 작업을 실행해 보세요. 그런 다음 검증을 통과한 조합을 모델 매핑 테이블에 등록하면 돼요. 신규 사용자는 무료 테스트 크레딧으로 먼저 검증할 수 있어요.
모델 API 오류 자주 묻는 질문 FAQ
결론: 아래 다섯 가지 질문은 운영 환경에서 가장 자주 논의되는 상황을 다뤄요. 답변의 원칙은 모두 같아요. 먼저 판단하고, 그다음 조치하세요.
Q1: 401 오류가 나면 재시도해야 하나요?
아니요. `401`은 인증 실패를 뜻해요. 재시도하면 요청만 늘어나고 `429` 오류까지 발생할 수 있어요. API 키가 유효한지, `Authorization` 요청 헤더 형식이 올바른지, Base URL과 API 키가 같은 플랫폼에 속하는지 확인하세요. APIYI apiyi.com을 사용한다면 콘솔에서 API 키 상태를 확인할 수 있어요.
Q2: 429 오류가 나면 바로 모델을 바꿔야 하나요?
바로 바꾸는 것은 권장하지 않아요. 먼저 오류 응답 본문과 `Retry-After`를 확인하세요. 요청 속도나 동시 요청 제한에 걸렸다면 대기 후 1~2회 재시도하면 대개 복구돼요. 사용 한도를 소진했을 때 다른 경로로 전환하세요. 이때는 같은 등급의 예비 모델을 선택하고, 무조건 가장 비싼 모델로 바꾸지 마세요.
Q3: 스트리밍 출력이 중단되면 요청을 다시 보내야 하나요?
바로 다시 보내지 마세요. 스트림이 중단됐다고 해서 요청이 실패한 것은 아니에요. 이미 콘텐츠가 생성되고 비용이 발생했을 수 있어요. 먼저 수신한 토큰 수와 콘텐츠의 활용 가능성을 확인하세요. 사용할 수 있다면 유지하거나 이어서 생성하고, 사용할 수 없고 요청이 멱등하다면 1회 다시 보내세요. 실제 청구 금액은 콘솔의 사용량을 기준으로 확인하세요.
Q4: 도구 호출이 중복 실행되면 어떻게 하나요?
근본적인 해결책은 도구 계층에서 멱등성을 보장하는 거예요. 비즈니스 측의 멱등 키나 작업 ID로 중복을 제거하고, 같은 ID는 한 번만 실행하세요. 도구 호출이 타임아웃되면 먼저 작업 상태를 확인하고, 실행되지 않은 것이 확인된 후 재시도하세요. 이미 중복 실행됐다면 호출 ID로 로그를 추적해 추가 작업을 보상하거나 취소하세요.
Q5: 예비 모델로 전환한 후 200이 반환됐지만 결과가 올바르지 않다면 어떻게 하나요?
200은 요청이 성공했다는 뜻일 뿐, 작업 성공을 보장하지는 않아요. JSON 구조, 필수 필드, 도구 파라미터의 유효성 등을 자동으로 검증하세요. 검증 실패는 실패율에 포함하고 알림이나 수동 검토를 실행하세요. 특정 예비 모델 조합이 검증에 자주 실패한다면 매핑 테이블에서 제거하고 카나리 검증을 다시 진행하세요.
출시 전 체크리스트와 정리: 언제 재시도하고, 전환하고, 멈춰야 할까?
결론부터 말하면, 장애가 발생한 뒤 급하게 로직을 추가하는 것보다 출시 전에 아래 체크리스트를 하나씩 확인하는 편이 훨씬 안정적이에요. 이 기준을 기억하세요. 4xx는 먼저 수정하고, 5xx는 재시도를 검토하며, 멱등하지 않은 요청은 일단 멈추세요.
| 번호 | 확인 항목 | 통과 기준 |
|---|---|---|
| 1 | 먼저 오류 유형 판단 | 모든 상태 코드를 다섯 가지 유형 중 하나로 분류하고, 알 수 없는 오류는 기본적으로 재시도하지 않음 |
| 2 | 4xx는 자동 재시도하지 않음 | 400, 401, 402, 403, 404, 409, 422는 바로 알림을 보내거나 수정 |
| 3 | 그다음 재시도 또는 전환 결정 | 일시적인 오류만 최대 1~2회 재시도하며, 백오프와 지터 적용 |
| 4 | Retry-After 준수 | 응답 헤더가 있으면 해당 값에 따라 우선 대기 |
| 5 | 멱등성 확인 | 도구 호출, 쓰기 작업, 메시지 전송, 결제는 기본적으로 멈추고 상태를 확인한 뒤 결정 |
| 6 | 스트림 중단 처리 | 이미 받은 토큰과 비용을 먼저 확인하고 무작정 재실행하지 않음 |
| 7 | 대체 모델 확인 | 작업 유형별로 기능 확인표를 작성하고 검증 완료 |
| 8 | 모델 매핑 | 논리 이름과 모델 ID의 매핑이 콘솔과 일치 |
| 9 | 최종 출력 검증 | 전환 후 200 응답만 확인하지 않고 구조와 필드도 검증 |
| 10 | 로그와 훈련 | 주요 필드가 빠짐없이 기록되고, 대체 경로를 정기적으로 시험 |
모델 API 오류 처리 핵심 요약
- 언제 재시도할까?:
429,500,502,503,529와 멱등한 타임아웃 요청은 백오프를 적용해 제한된 횟수만 재시도해요. - 언제 전환할까?: 재시도해도 실패하거나, 업스트림을 계속 사용할 수 없거나, 사용 한도를 소진했을 때 대체 모델이 검증돼 있다면 전환해요.
- 언제 멈출까?:
401같은 4xx 설정 오류와 상태를 알 수 없는 비멱등 요청은 멈춰요. - 전환이 곧 성공은 아니에요: 대체 모델이 200을 반환한 뒤에도 출력을 검증해야 해요.
- 게이트웨이와 애플리케이션의 역할 분담: 연결 경로의 가용성은 게이트웨이가, 작업의 정확성은 비즈니스 코드가 담당해요.
오류 처리를 잘한다는 건 무조건 적극적으로 재시도하는 게 아니라, 오류가 발생할 때마다 올바르게 판단하는 거예요. 먼저 오류 분류, 멱등성 태그, 로그 필드를 정비한 뒤 대체 모델을 단계적으로 도입해 보세요. 대체 경로로는 APIYI apiyi.com을 고려할 수 있어요. 하나의 키로 여러 주요 모델을 사용할 수 있어 같은 코드로 주 모델과 대체 모델을 검증하고 전환하기 편리해요. 가격과 가용성은 콘솔과 문서를 확인하세요.
📚 참고 자료
- APIYI 문서 센터: 연동 방법, 모델 목록 및 요금 안내
- 링크:
docs.apiyi.com -
참고: 모델 ID, 가격 및 사용 가능 여부는 문서와 콘솔을 확인하세요.
-
HTTP 상태 코드 설명:
Retry-After등 표준 응답 헤더의 의미 - 링크:
developer.mozilla.org/docs/Web/HTTP/Status - 참고: 4xx, 5xx의 일반적인 의미를 설명해요. 구체적인 오류 내용은 각 모델 플랫폼의 오류 응답을 확인하세요.
작성자: APIYI 기술팀
기술 문의: APIYI 공식 사이트 apiyi.com의 홈페이지에서 문의해 주세요. 더 많은 연동 자료는 docs.apiyi.com 문서 센터에서 확인할 수 있어요.
