Blocked API Keys (차단된 API 키)
경로: Admin → System Management → Blocked API Keys
문서 처리 파이프라인에서 API 인증 오류·사용량 문제 로 자동 차단된 외부 API 키를 관리합니다. 차단된 키를 해제하면 관련 문서가 PENDING 상태로 복원되어 재처리됩니다.
목록 구성
| 컬럼 | 설명 | 예시 |
|---|
| API Key | 차단된 키 (접두사만 표시) | shsk_PXQ... |
| Error Code | 차단 원인 HTTP/서비스 코드 | 402 / 401 / 429 |
| API Type | 사용 유형 | Embedding / 문서 분석 / 표 추출 등 |
| Tenant | 속한 테넌트 (Workspace) | user@example.com's Workspace |
| Occurred At | 차단 발생 시각 | 2026. 4. 20. 오전 1:52:58 |
| Actions | [해제] 버튼 | |
차단 대상 API 유형
| 유형 (내부 코드) | 설명 |
|---|
base_vlm | 문서 분석 (Vision Language Model) |
table_vlm | 표 추출 |
embedding | 임베딩 생성 |
refine_llm | 텍스트 정제 |
normalize_llm | 텍스트 정규화 |
Error Code 의미
| 코드 | 원인 | 조치 |
|---|
| 401 | Unauthorized — 키 만료/오류 | 키 재발급 |
| 402 | Payment Required — 결제·잔액 문제 | 빌링 확인 / 한도 상향 |
| 403 | Forbidden — 권한 부족 | 키 권한 범위 확인 |
| 429 | Rate Limit — 사용량 초과 | 요금제 변경 / 재시도 간격 조정 |
| 기타 5xx | 공급자 서버 오류 | 재시도 / 공급자 상태 확인 |
- 테넌트 필터 — 전체 또는 특정 테넌트의 차단된 키만 조회
해제 (Unblock)
개별 해제
각 행의 [해제] 버튼. 단일 키 해제.
전체 해제
상단 [Unblock All] 버튼. 필터 범위 내 모든 차단 해제.
[Unblock All] 실행 시 확인 다이얼로그 표시:
“N개의 차단된 API 키를 모두 해제하시겠습니까? 관련 문서들이 PENDING 상태로 복원됩니다.”
해제 시 동작
원인 파악
Error Code 확인. 401/402/403/429 각각 다른 조치 필요.
근본 원인 해결
- 키 재발급 (401)
- 결제·한도 조정 (402, 429)
- 권한 재설정 (403)
해제 실행
[해제] 또는 [Unblock All] 클릭.
문서 상태 복원
관련 문서가 PENDING 으로 전환 → 다음 vsync 처리 주기에 재시도.
근본 원인 미해결 시 재차단 — 키 자체의 문제를 해결하지 않고 해제만 반복하면 같은 키가 즉시 다시 차단됩니다. Error Code 먼저 확인하세요.
차단·해제 이력은 Events 감사 로그에 기록됩니다.
Actor: 시스템 자동 차단은 system, 해제는 실행한 admin 이메일. 관련 문서
