한도

AI Gateway에서는 비용을 Service / Member / Key 단위로 통제합니다. 한도는 USD 원가 기준 월 지출 상한이며, 한 단계라도 한도를 넘으면 호출이 거부됩니다.

이 문서는 현재 화면에서 확인하거나 설정할 수 있는 범위와 호출이 막히는 기준만 다룹니다.

한도 개요

한도를 여러 단계로 나누면 막을 범위를 좁힐 수 있습니다. Space 전체 상한만 있으면 한 멤버가 예산을 혼자 다 써도 세밀하게 막기 어렵고, 키 하나만 막으려 해도 전체 운영 정책을 손대야 합니다.

막히는 단계에 따라 영향 범위가 다릅니다.

• Key Limit 도달: 그 키 한 개만 막힙니다. 같은 멤버의 다른 키는 그대로 동작합니다.
• Member Limit 도달: 그 멤버의 모든 키가 동시에 막힙니다. 다른 멤버는 영향받지 않습니다.
• Service Limit 도달: Space의 모든 호출이 막힙니다. 마지막 안전망입니다.

단위와 리셋

리셋 시점은 키 생성일이 아니라 달력 기준입니다. 4월 28일에 만든 키도 5월 1일 00:00 KST에 리셋합니다.

초기 세팅값

AI Gateway를 처음 활성화하면 모든 한도는 미설정 상태로 시작합니다. 미설정은 무제한을 뜻하며, 해당 단계에서는 한도 차단이 일어나지 않습니다.

한도 초과 응답

요청이 한도에 막히면 429 Too Many Requests 응답이 돌아옵니다. 본문에는 어느 단계의 한도인지가 담깁니다.

{
  "type": "https://gw.letsur.ai/errors/key-limit-exceeded",
  "title": "Key limit exceeded",
  "status": 429,
  "detail": "이 키의 이번 달 한도를 모두 사용했습니다.",
  "limit": "50.00 USD",
  "reset_at": "2026-06-01T00:00:00+09:00"
}

type은 key-limit-exceeded, member-limit-exceeded, service-limit-exceeded 중 하나입니다. 자세한 에러 코드 체계는 에러 코드에서 확인합니다.

트레이드오프

Service Limit으로 Space 월 예산 막기

Service Limit는 Space 전체의 월 지출 상한입니다. Key·Member 한도를 통과한 호출이 마지막으로 만나는 단계라, 한 멤버나 키 하나가 Space 예산을 다 쓰는 일을 여기서 막습니다.

시작 전 알아야 할 것

• 본인이 Gateway Admin이어야 합니다(역할).
• 단위는 USD 원가 기준이며, 쓴 공급사 토큰 비용의 합입니다(단가).
• Service Limit는 가장 넓은 마지막 단입니다. Key·Member 한도가 먼저 막고, 이 둘을 통과한 호출이 마지막에 Service Limit를 만납니다.

설정

Space의 AI Gateway 한도 설정 화면에서 월 상한을 저장합니다. 화면에 노출된 항목만 직접 조정합니다.

한도 변경

같은 화면에서 값을 바꿔 저장합니다. 변경은 다음 호출부터 적용됩니다.

한도를 넘긴 상태에서 한도를 올리면 다시 호출이 통합니다. 한도를 내리면 다음 호출부터 새 기준으로 막힙니다.

한도 초과 시

요청이 Service Limit에 막히면 429 응답이 돌아옵니다. 본문에 service-limit-exceeded가 들어갑니다.

미설정 시

한도가 비어 있으면 무제한이며, 이게 초기값입니다. 미설정 상태로 외부 사용을 시작하면 사고가 나도 막을 자리가 없으므로, 첫 Admin은 운영 전 월 예산을 정합니다.

운영 권장

• 합의한 월 예산을 그대로 넣습니다.
• Service Limit는 마지막 안전망이므로, 여유는 하위 단(Member·Key)에서 둡니다.
• 변경하기 전에 멤버에게 미리 알립니다. 한도 변경은 멤버 전원에게 영향을 줍니다.

Member 한도로 멤버 월 예산 막기

Member 한도는 멤버 한 명의 월 지출 상한입니다. 그 멤버가 가진 모든 키의 합산 사용이 상한을 넘지 못하게 막습니다. 멤버마다 실험과 작업 예산을 다르게 줘야 할 때 사용합니다.

시작 전에

• 본인이 Gateway Admin이어야 합니다(멤버 역할).
• 단위는 USD 원가 기준입니다.
• 멤버가 가진 키 여러 개를 합산한 값입니다. Key 한도는 그 멤버의 키 하나에 거는 한도입니다.

한도 모델

설정하기

변경하면 일어나는 일

한도 초과 시

자주 만나는 오류

해결 확인

한도를 올린 멤버가 다시 호출해 429가 아닌 정상 응답을 받으면 적용된 것입니다. 여전히 막히면 응답 본문의 type 필드로 어느 단에서 막혔는지 확인합니다.

Key Limit으로 키 한 개의 월 지출 막기

Key Limit은 키 한 개의 월 지출 상한입니다. 한도를 걸면 그 키가 상한에 닿는 즉시 차단되므로, 외부 도구에 넣은 키가 폭주해도 피해를 그 키 한 개로 막아냅니다.

시작 전 알아야 할 것

Key Limit은 한도 모델에서 가장 좁은 첫 번째 단입니다. 키가 막히면 멤버나 Service 한도까지 가지 않고 그 키에서 호출이 끊깁니다. 새 키를 만들거나 Claude Code 같은 외부 도구에 키를 넣을 때 안전장치로 둡니다.

• 한도를 정하는 사람: 키 소유자입니다. Admin과 Member 모두 자기 키에 한도를 겁니다.
• 단위: 월 USD입니다. 단가는 단가를 봅니다.
• 자동 리셋: 매월 1일 00:00 KST입니다.

키 만들 때 한도 설정

새 키는 발급하면서 바로 한도를 겁니다.

기존 키에 한도 부여

이미 만든 키에도 한도를 새로 걸거나 바꿀 수 있습니다.

한도 초과 시 동작

한도에 닿으면 그 키만 차단되고 다른 키는 계속 동작합니다.

권장 운영 패턴

키 용도에 맞춰 한도 폭을 정합니다.

한도와 비활성화의 차이

차단 방식이 셋으로 나뉩니다.

자세한 내용은 키 라이프사이클을 봅니다.

자주 만나는 오류

관련 문서