BizRouter 비즈라우터

오류 처리

BizRouter에서 생성한 오류와 LLM Provider가 반환한 오류는 응답 형식이 다를 수 있습니다. 클라이언트는 HTTP status를 먼저 확인하고, 가능한 경우에만 error.code 를 사용해야 합니다. 두 가지 오류 응답 형식 BizRouter 자체 오류는 표준 구조로 반환됩니다. Provider가 status와 body를 제공한 경우에는 원본 status와 오류 body가 그대로 전달될 수 있으므로 모든 실패 응답에 BizRouter의 code/type/details 가 있다고 가정하지 마십시오.

BizRouter 오류 형식

BizRouter에서 생성한 오류의 기본 JSON 구조입니다. code : 프로그램에서 분기할 안정적인 BizRouter 오류 코드 message : 진단용 설명. 문자열 자체를 분기 조건으로 사용하지 마십시오. type : 오류 범주 details : 재시도 가능 여부 등 선택 정보

Provider 오류 passthrough

Provider가 반환한 status와 body는 Provider 고유 형식으로 전달될 수 있습니다. Provider 오류의 code , type , HTTP status는 Provider마다 다릅니다. 알 수 없는 body도 로그에 안전하게 남길 수 있도록 클라이언트를 구현하십시오.

주요 BizRouter 오류 코드

고객 애플리케이션에서 직접 처리할 가능성이 높은 오류입니다. 조치:

선불 크레딧 오류

두 403 응답은 재시도 정책이 다릅니다. prepaid_credit_temporarily_reserved : 짧은 backoff 후 재시도할 수 있습니다. prepaid_credit_exhausted : 충전 전에는 재시도하지 마십시오.

안전한 오류 처리 예제

JSON이 아닌 응답과 Provider 고유 body도 처리합니다. JavaScript Python

재시도 판단 · 제한적으로 재시도

details.retryable=true 429와 Retry-After 502, 503은 중복 생성·과금을 허용할 수 있을 때만 제한적으로 재시도 network timeout은 처리 결과를 알 수 없으므로 사용량 로그 확인 후 판단

재시도 판단 · 요청 수정 전 재시도 금지

400, 401, 404 대부분의 403 model/IP scope 위반 크레딧 소진 또는 사용 한도 초과 403을 status만으로 판단하지 마십시오 prepaid_credit_temporarily_reserved 는 403이지만 details.retryable=true 일 수 있습니다. 생성 요청은 멱등하지 않습니다 Chat Completions 같은 생성 요청은 timeout이나 5xx 전에 Provider에서 이미 처리되었을 수 있습니다. 자동 재시도는 중복 응답과 중복 비용을 만들 수 있습니다. X-BizRouter-Client-Request-Id 는 사용량 로그 대조용이며 idempotency key가 아닙니다.

invalid_api_key 401 API Key가 없거나 유효하지 않음 Key와 인증 header를 확인한 뒤 요청을 수정 bad_request 400 요청 형식 또는 parameter가 유효하지 않음 요청을 수정하고 재전송 forbidden_content 400 조직의 콘텐츠 정책에 의해 차단됨 입력을 수정하거나 조직 관리자에게 정책 확인 invalid_route_allowed_models 400 X-BizRouter-Route-Allowed-Models 헤더 형식이 잘못됨 메시지가 알려 주는 항목(허용 문자·개수·길이)을 고쳐 재전송 file_upload_blocked 403 조직에서 file/image 입력을 허용하지 않음 텍스트 요청으로 변경하거나 조직 관리자에게 문의 model_blacklisted 403 조직에서 해당 모델을 차단함 다른 모델을 선택하거나 조직 관리자에게 문의 api_key_ip_not_allowed 403 호출 IP가 API Key allowlist에 없음 고정 egress IP 또는 API Key의 IP 설정 확인 api_key_model_not_allowed 403 API Key의 model scope에 포함되지 않음 허용 모델을 사용하거나 Key의 model scope 변경 provider_blocked 403 조직 또는 그룹 정책이 해당 프로바이더를 차단함 다른 모델·프로바이더를 선택하거나 조직 관리자에게 문의 prepaid_credit_exhausted 403 선불 크레딧 소진 크레딧 충전 후 재시도 prepaid_credit_temporarily_reserved 403 진행 중 요청이 잔여 크레딧을 임시 예약함 details.retryable을 확인하고 짧은 backoff 후 재시도 credit_limit_exceeded 403 조직 사용 한도 초과 조직 한도를 확인한 뒤 재시도 api_key_credit_limit_exceeded 403 API Key 사용 한도 초과 Key 한도를 확인하거나 다른 Key 사용 user_monthly_limit_exceeded 403 구성원 월 한도 초과(그 구성원의 모든 Key 합산) 조직 관리자가 구성원 월 한도를 조정 model_not_found 404 모델이 없거나 현재 Key에 노출되지 않음 GET /v1/models 결과에서 model ID 선택 idempotency_conflict 409 같은 Idempotency-Key 요청이 처리 중이거나 막 끝남 재전송하지 말고 원래 요청 결과 확인 request_body_too_large 413 요청 본문이 허용 크기를 넘음 본문을 줄이거나 큰 파일은 나누어 전송 rate_limit_exceeded 429 요청 빈도 제한 초과 Retry-After 후 재시도 provider_error 502 Provider 연결 또는 처리 실패 지수 backoff로 제한적으로 재시도 service_unavailable 503 BizRouter가 일시적으로 요청을 처리할 수 없음 지수 backoff로 재시도 provider_timeout 504 모델 제공사 응답이 시간 제한을 넘음 출력 길이를 줄이거나 잠시 후 재시도

주식회사 AI3 | 서울 강남구 영동대로85길 34 | support@bizrouter.ai