본문으로 건너뛰기

월 사용 한도

API 키별 한도와 구성원별 월 한도 관리

개인 키에 함께 적용되는 API 키 한도와 구성원 한도를 구분하고, 역할별 설정 범위와 새 구성원 기본 한도, 차단 시 대응을 안내합니다.

페이지 목차

한도 종류 선택

AI 게이트웨이에는 API 키 월 한도와 구성원 월 한도가 있습니다. 개인 키로 요청하면 두 한도가 함께 적용됩니다.

구분API 키 월 한도구성원 월 한도
제한하는 대상API 키 한 개한 사람이 만든 모든 개인 키
알맞은 용도업무, 자동화 또는 외부 도구 하나의 사용량 제한구성원 한 사람의 전체 사용량 제한
사용량 계산해당 키로 사용한 양해당 구성원의 모든 개인 키로 사용한 양의 합계
새 키를 만들면새 키에 별도 한도를 설정할 수 있음새 키에도 같은 구성원 한도가 계속 적용됨
관리하는 사람키를 만든 사람. 스페이스 관리자(Admin)도 화면에 그 키가 보이면 관리 가능Admin

같은 키로 호출하는 지원 API에는 엔드포인트와 관계없이 같은 API 키 월 한도가 적용됩니다. 현재 스페이스의 API 키 관리 화면에는 키별 월 한도와 제한 없음 여부가 표시됩니다. 모델별 단가와 지원 범위는 현재 모델 단가와 지원 API 보기에서 확인합니다.

사용 목적과 호출 변동 폭을 함께 고려해 한도를 정합니다. 운영 환경에 연결한 뒤에는 누적 사용량을 분석에서 점검하고, 유닛의 보유 상태와 초과 상태는 유닛에서 확인합니다.

시나리오고려할 점
외부 AI 도구반복 호출이 발생해도 감당할 수 있는 범위인지 확인합니다
사내 자동화와 봇평소 업무량과 일시적인 호출 증가를 함께 고려합니다
일회성 실험실험 기간과 만료일을 함께 검토합니다

한도를 설정할 수 있는 역할

작업AdminMember
자신의 API 키 한도 설정 및 변경가능가능
다른 사용자의 API 키 한도 설정 및 변경가능불가
자신의 구성원 한도 확인가능API 키 화면에서 가능
자신의 구성원 한도 변경가능불가
Member의 구성원 한도 확인 및 변경가능불가
다른 Admin의 구성원 한도 확인가능불가
다른 Admin의 구성원 한도 변경한도 설정 화면에서 불가불가
새 구성원 기본 한도 확인 및 변경가능불가

Admin은 한도 설정 화면에서 조직의 구성원별 사용량과 한도를 관리합니다. 역할별 키 조회 및 관리 범위는 API 키와 구성원 권한에서 확인합니다.

내 사용량과 한도 확인하기

AI 게이트웨이 > API 키 화면 상단에서 이번 달 내 사용량과 내 한도를 확인할 수 있습니다.

  • 이번 달 내 사용량은 자신이 만든 모든 개인 키의 이번 달 사용량을 합한 값입니다.
  • 내 한도는 개인 키 하나가 아니라 자신이 만든 모든 개인 키에 함께 적용되는 구성원 월 한도입니다.

화면에 보이는 상태에 따라 다음과 같이 대응합니다.

화면에서 본 것뜻과 다음 행동
구성원 월 한도 80% 경고이번 달 내 사용량이 구성원 월 한도의 80%를 넘었다는 뜻입니다.
구성원 월 한도에 도달함새 키를 만들어도 같은 구성원 한도가 적용됩니다. Member는 Admin에게 한도 변경을 요청하고, Admin은 AI 게이트웨이 > 한도 설정에서 자신의 한도를 변경합니다.
이번 달 내 사용량만 보이고 내 한도는 보이지 않음구성원 월 한도가 설정되지 않았을 수 있습니다. Admin은 AI 게이트웨이 > 한도 설정에서 자신의 한도를 확인하고, Member는 Admin에게 확인을 요청합니다. 이 표시만으로 키별 한도나 다른 호출 제한까지 없다고 판단하지 마세요.

한도가 적용되는 시점과 예외

이번 달 사용량은 매월 1일 00:00 KST부터 새 달 기준으로 집계됩니다. 한도 값과 상황에 따른 동작은 다음과 같습니다.

상황동작
요청 시점에 사용량과 한도를 정상적으로 확인했고, 사용량이 한도 이상게이트웨이가 새 호출을 차단합니다
API 키 월 한도를 설정하지 않음해당 키의 월 한도가 제한 없음으로 표시됩니다
키 화면의 제한 없음그 키의 월 한도만 적용되지 않습니다. 구성원 월 한도, API 키 인증, 모델 접근 범위 및 보유 유닛에 따른 차단은 그대로 유지됩니다
신규 구성원 기본 월 한도에 0을 입력월 한도를 0 unit으로 정한 값이며 제한 없음으로 처리되지 않습니다
사용량이나 한도를 확인하는 과정에 오류 발생게이트웨이가 그 한도를 근거로 요청을 차단하지 않고 허용할 수 있습니다. API 키 인증, 모델 접근이나 보유 유닛에 따른 별도 제한은 해제되지 않습니다
월 사용 한도는 최종 지출이 설정값을 넘지 않도록 보장하지 않습니다

이미 진행 중인 요청의 비용이 나중에 반영되면 누적 사용량이 한도를 넘을 수 있습니다. Batch에서는 게이트웨이가 아직 정산되지 않은 작업의 비용을 미리 예약하지 않습니다. 제출한 작업의 비용이 나중에 확정될 수 있으므로 월 한도만으로 전체 지출이 설정값 이하에 머문다고 보장할 수는 없습니다.

초과 사용이 허용된 스페이스라도 API 키나 구성원의 사용 한도를 이미 초과했다면 신규 Batch 제출이 차단될 수 있습니다. 접수된 Batch의 비용이 확정되는 시점은 Batch의 확정 비용 확인하기에서 확인합니다.

제출한 달과 정산된 달이 달라 비용이 반영되는 달을 확인해야 한다면 Batch ID와 제출 시각, 정산 시각을 기록해 플랫폼 내 문의 기능으로 확인을 요청합니다.

API 키 월 한도 정하기

API 키 월 한도는 unit 단위로 입력하며, 입력란을 비우면 제한 없음으로 저장됩니다.

  1. 대상 키 확인하기

    AI 게이트웨이 > API 키에서 현재 스페이스가 맞는지 보고, 대상 키의 이름과 소유자를 확인합니다. Member는 내 키, Admin은 필요에 따라 내 키 또는 전체 키에서 찾습니다.

  2. 수정 화면에서 한도 입력하기

    대상 키의 수정 화면을 열고 월 한도를 unit 단위로 입력합니다. 제한을 두지 않으려면 입력란을 비웁니다.

  3. 저장 결과 확인하기

    저장한 뒤 키 목록이나 상세 화면에 월 한도 또는 제한 없음 상태가 표시되는지 확인합니다. 차단된 호출을 다시 시작하기 전에 최근 사용량을 확인하고, 새 한도가 의도한 값인지도 확인합니다.

구성원 월 한도 관리하기

Admin은 AI 게이트웨이 > 한도 설정에서 구성원 전체의 사용량과 한도를 확인하고, 자신과 Member의 월 한도를 변경할 수 있습니다.

  1. 구성원 상태 확인하기

    이름, 역할, 이번 달 사용량, 월 한도와 사용률을 확인합니다. 자신의 한도와 Member의 한도는 변경할 수 있습니다. 다른 Admin의 한도는 이 화면에서 변경할 수 없으므로 그 Admin이 자기 한도를 직접 변경하도록 요청합니다.

  2. 한 명 또는 여러 명 선택하기

    구성원 한 명의 수정 버튼을 선택하거나, 자신과 Member 중에서 변경할 대상을 여러 명 선택합니다. 여러 명을 동시에 변경할 때는 선택한 구성원과 인원 수를 다시 확인합니다.

  3. 한도 저장하고 결과 확인하기

    월 한도를 unit 단위로 입력하거나 제한 없음으로 바꾼 뒤 저장합니다. 여러 명을 선택했다면 같은 설정이 선택한 구성원 모두에게 적용됩니다. 이미 사용한 양과 같거나 낮은 한도를 저장하면 다음 호출이 중단될 수 있다는 경고가 표시됩니다. 저장 뒤 대상 구성원의 월 한도가 바뀌었는지 확인합니다.

새 구성원 기본 월 한도 정하기

저장한 기본 한도는 이후 참여하는 구성원에게만 적용됩니다. 적용 여부는 초대 링크를 전달한 시점이 아니라 구성원이 참여한 시점을 기준으로 정해집니다. 기본 한도는 AI 게이트웨이 > 한도 설정 상단의 신규 구성원 기본 월 한도에서 정합니다.

  1. 현재 기본 한도 확인하기

    화면 상단에서 현재 값을 확인하고 수정 버튼을 선택합니다. 새 스페이스에는 숫자형 기본 한도가 자동으로 설정되지 않으며, 스페이스를 만든 첫 Admin의 구성원 한도도 자동으로 생기지 않습니다.

  2. 제한 없음 또는 직접 지정 선택하기

    구성원 월 한도를 두지 않으려면 제한 없음을 선택합니다. 값을 정하려면 직접 지정을 선택하고 unit 단위로 입력합니다. 0을 입력하면 월 한도가 0 unit으로 정해지며 제한 없음으로 처리되지 않습니다.

  3. 저장하고 적용 대상 확인하기

    저장해도 이미 참여 중인 구성원의 한도는 바뀌지 않으므로, 한도를 바꿔야 할 구성원은 목록에서 선택해 개별로 변경합니다. 새 구성원이 스페이스에 참여하면 구성원 목록에서 실제 한도를 확인하고, 설정한 값과 다르면 그 구성원의 한도를 변경합니다.

한도에 도달했을 때

한도 오류를 받으면 오류 응답의 HTTP 상태, type, detail, error_ref를 확인합니다.

오류 코드뜻과 먼저 확인할 것
429 policy_limit_exceeded한도 정책이 요청을 거부한 오류입니다. 실시간 호출과 Batch 신규 제출에서 발생할 수 있습니다. 응답의 scope_kind, policy_type, rule_key가 있으면 적용 대상과 정책을 확인합니다
429 usage_limit_exceeded사용 제한에 도달한 오류입니다. 코드만으로 키 월 한도나 해제 시점을 단정하지 않고, 응답 상세에서 적용 대상과 해제 조건을 확인합니다

응답에 scope_kind, policy_type, rule_key가 있으면 그 값을 그대로 기록합니다. 값이 없으면 추정한 값을 기록하지 않습니다.

한도를 초과한 상태에서 같은 요청을 반복하거나 우회하지 마세요

새 API 키를 만들어도 구성원 한도는 계속 적용됩니다. Batch 제출에서 Idempotency-Key를 바꾸어 한도를 우회하지 마세요. 제출 응답을 받지 못해 원래 작업을 확인하는 재시도는 같은 요청 키와 본문을 유지하는 조건을 따릅니다.

요청을 거부한 한도가 콘솔에서 설정한 월 한도라면 요청에 사용한 API 키의 월 한도와 사용량을 확인합니다. 개인 키라면 키를 만든 사람의 구성원 월 한도와 이번 달 사용량도 함께 확인합니다.

확인하거나 변경하려는 상황다음 행동
다른 사람이 만든 키여서 값을 볼 수 없음키를 만든 사람이나 Admin에게 확인을 요청합니다.
Member가 구성원 한도를 변경해야 함직접 변경할 수 없으므로 Admin에게 변경을 요청합니다.
Admin이 구성원 한도 변경을 검토함한도 설정 화면에서 해당 구성원의 사용량과 한도를 확인한 뒤 변경 여부를 판단합니다.

한도를 올리거나 제한 없음으로 저장하기 전에 키의 사용처와 최근 사용량을 확인합니다. 응답과 화면에 표시된 한도와 사용량만으로 적용 대상이나 해제 조건을 확인할 수 없다면 error_ref와 키 이름을 포함한 진단 정보를 준비해 문의합니다.