Claude apps gateway 지출 한도
공식 기준: https://code.claude.com/docs/en/claude-apps-gateway-spend-limits
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
Spend limits는 Claude apps gateway를 통과하는 개발자(또는 그룹·조직) 지출을 일/주/월 단위로 캡합니다. 초과 시 다음 요청에 429 (error.type: billing_error, x-should-retry: false)를 반환합니다. 공유 upstream 자격증명 위에서 한 runaway agent가 조직 commitment를 소진하는 것을 막는 회로 차단기입니다.
한도 값은 YAML이 아니라 Admin API로 설정합니다. YAML admin은 API 키·기능 활성·blocked_message·retention을 켭니다.
핵심 개념
- 기간: daily / weekly / monthly
- 범위: per-user, group, organization
- 과금 추정: 스트림 token × USD list price (인보이스가 아닌 추정치)
/v1/messages/count_tokens는 한도 검사 면제- Postgres 장애 시 기본 fail-open;
enforcement.fail_closed_on_error: true로 fail-closed
상세
인증 (Admin API)
admin.write_keys/admin.read_keys— 키id가 감사에admin-key:<id>로 기록- 또는
admin.admin_groups에 속한 OIDC bearer —oidc:<sub>로 감사, 인간 admin에 적합
강제 동작
각 /v1/messages에서 Postgres 한 번 조회로 캡·기간 누적을 확인합니다. 초과 시 메시지 spend limit reached + 선택 admin.blocked_message.
응답 스트림을 읽으며 token을 미터링하고 세 기간 버킷을 증가시킵니다. 미터 실패가 클라이언트 바이트를 깨지 않습니다. 인식 불가 모델 ID는 기본 $5/$25 per MTok 입력/출력으로 과금 추정(0으로 우회 방지). 클라이언트 abort도 terminal usage 프레임이 없으면 스트림 크기 기반 conservative floor로 과금합니다.
Admin API (/v1/organizations/spend_limits)
| 메서드 | 설명 |
|---|---|
GET .../spend_limits |
캡 목록 (limit, after_id, before_id) |
POST .../spend_limits |
{scope, period} 생성/교체 |
GET/DELETE .../spend_limits/{id} |
spl_ ID 조회·삭제 |
GET .../effective |
주체별 해석 캡·누적 지출 |
GET .../audit |
변경 감사 로그 |
금액은 USD cents 정수 문자열. Anthropic Admin API 관례(type, 에러 envelope, request-id)를 따릅니다. mutation은 동일 트랜잭션으로 admin_audit before/after 기록.
/effective
OIDC sub 기준. actor email/name은 첫 inference 전까지 null. groups는 마지막 관측 IdP 그룹(게이트웨이 확장). 쿼리: user_ids[], period[], sort=spend_desc, q, limit/page.
q/user_ids[]는 GET 쿼리에 실리므로 프록시 액세스 로그 PII 정책을 검토하세요.
데이터 수명
| 테이블 | 내용 | 기본 보존 |
|---|---|---|
spend |
기간 누적 cents | spend_retention_months (13) |
spend_limits |
캡 설정 | API 삭제 시까지 |
admin_audit |
변경 이력 | audit_retention_days (365) |
principal_emails |
email/name/groups (PII) | identity_retention_days (90, 마지막 활동 기준) |
오프보딩: per-user 캡 DELETE 후 retention으로 자연 소멸. 즉시 삭제(DSAR)는 principal_emails에서 해당 sub row 삭제. spend/audit는 가명 sub만 참조.
체크리스트
- admin write/read 키 분리
- 기본 per-dev 캡 정의
- fail-open vs fail-closed 선택
- 429 메시지·상향 프로세스
- retention·DSAR 절차 문서화
- provider 청구와 주기적 대사