에러 코드

HTTP 상태 코드와 detail 필드로 에러를 반환합니다.

상태 코드

코드	이름	설명
400	Bad Request	잘못된 요청. 지원하지 않는 모델 ID, 허용되지 않은 모델/티어(키 스코프 제한), 파라미터 범위 초과 등.
401	Unauthorized	API 키 누락, 유효하지 않은 키, 만료된 키, 또는 삭제된 사용자.
402	Payment Required	크레딧 부족(insufficient_credits) 또는 월 예산 한도 초과. 충전 후 다시 시도하세요.
403	Forbidden	PIPA 동의 필요(pipa_consent_required). 해당 데이터 티어 사용에 추가 동의가 필요합니다.
429	Too Many Requests	Rate limit 초과. API 키별 기본 60 RPM. 잠시 후 다시 시도하세요.
502	Bad Gateway	업스트림 프로바이더 오류. 자동 재시도와 폴백 이후에도 실패한 경우입니다. 크레딧은 차감되지 않습니다.

구조화된 에러

과금/동의 관련 에러는 detail.error에 기계가 판별할 수 있는 코드 문자열이 들어 있습니다.

402 — insufficient_credits

{
  "detail": {
    "error": "insufficient_credits",
    "message": "사용 가능 크레딧 부족: ₩120 < ₩540"
  }
}

403 — pipa_consent_required

{
  "detail": {
    "error": "pipa_consent_required",
    "message": "global 티어 사용에는 국외이전 동의가 필요합니다",
    "tier": "tier3",
    "provider": "openai"
  }
}

재시도 가이드

429와 502는 지수 백오프로 재시도하세요. 서버가 이미 프로바이더 호출을 2회 재시도하고 Tier 1 모델은 폴백 체인까지 시도하므로, 클라이언트 재시도 간격은 1초 이상을 권장합니다. 4xx는 요청을 수정하기 전까지 재시도해도 같은 결과입니다.