// data catalog / errors
에러 코드
모든 에러 응답은 {"code": "...", "message": "...", "requestId": "..."} 모양이다. 검증 실패는 fieldErrors 배열을 더한다. code 는 정규화된 enum 이라 자동화 분기에 안전하게 쓸 수 있다.
HTTP 400 — 요청 형식·값 오류
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| ACTION_NOT_SUPPORTED | 해당 프로바이더에서 지원하지 않는 액션입니다 | — |
| ALREADY_FREE_NO_OP | 이미 FREE 플랜이라 해지할 수 없습니다 | — |
| API_KEY_ALREADY_REVOKED | 이미 폐기된 API 키입니다 | — |
| DATE_RANGE_EXCEEDED | 허용된 최대 조회 기간을 초과했습니다 | — |
| DATE_RANGE_INVALID | 조회 기간 범위가 유효하지 않습니다 | — |
| DELIVERY_ROUTE_NOT_FOUND | 해당 워크스페이스에 배달 경로가 설정되지 않았습니다 | — |
| DEVICE_CODE_EXPIRED | 만료된 device_code 입니다. 다시 시도해 주세요 | — |
| DEVICE_CODE_INVALID | 유효하지 않은 device_code 입니다 | — |
| INVALID_BUSINESS_REGISTRATION_NUMBER | 사업자등록번호 형식이 올바르지 않습니다 | — |
| INVALID_CREDENTIAL_FORMAT | 인증 필드 형식이 올바르지 않습니다 | — |
| INVALID_CURSOR | 유효하지 않은 커서입니다 | — |
| INVALID_DATA_JOB_PARAMS | 요청 파라미터가 올바르지 않습니다 | — |
| INVALID_PARAM_FORMAT | 파라미터 형식이 올바르지 않습니다 | — |
| INVALID_PROVIDER_CODE | 지원하지 않는 프로바이더 코드입니다 | — |
| MALFORMED_REQUEST | 요청 본문 형식이 올바르지 않습니다 | — |
| MISSING_CREDENTIAL_FIELD | 필수 인증 필드가 누락되었습니다 | — |
| MISSING_PARAMETER | 필수 파라미터가 누락되었습니다 | — |
| MISSING_REQUIRED_PARAM | 필수 파라미터가 누락되었습니다 | — |
| NO_PENDING_PLAN_CHANGE | 취소할 예약된 플랜 변경이 없습니다 | — |
| PARTNER_BUSINESS_SELECTOR_REQUIRED | X-H6S-Business 헤더(사업자등록번호)가 필요합니다 | — |
| PARTNER_NAME_INVALID | 파트너 이름이 유효하지 않습니다 | — |
| PAYMENT_METHOD_REQUIRED | 결제수단을 먼저 등록해 주세요 | — |
| PERSONAL_EMAIL_NOT_ALLOWED | 회사 업무용 이메일로 가입해 주세요. 회사 이메일을 사용할 수 없는 경우 영업팀(h6s@bolta.io)으로 문의해 주세요 | — |
| PROVIDER_CODE_MISMATCH | 요청한 기관과 자격증명에 묶인 기관이 다릅니다 | — |
| PROVIDER_CODE_REQUIRED_FOR_GLOBAL_CERT | 공동인증서 자격증명은 어느 기관으로 호출할지 함께 지정해야 합니다 | — |
| PROVIDER_DOES_NOT_ACCEPT_CERT_LOGIN | 이 기관은 공동인증서 로그인을 지원하지 않습니다 | — |
| SAME_PLAN_CHANGE | 이미 같은 플랜입니다 | — |
| SUBSCRIPTION_NOT_PAST_DUE | 결제 실패 상태가 아닙니다 | — |
| UNSUPPORTED_AUTH_METHOD | 지원하지 않는 인증 방식입니다 | — |
HTTP 401 — 인증 실패
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| INVALID_CREDENTIALS | 이메일 또는 비밀번호가 올바르지 않습니다 | — |
| INVALID_TOKEN | 유효하지 않은 토큰입니다 | — |
| TOKEN_EXPIRED | 만료된 토큰입니다 | — |
| WEBHOOK_SIGNATURE_INVALID | 웹훅 서명이 유효하지 않습니다 | 전파 |
HTTP 402 — 기타
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| CARD_DECLINED | 카드사에서 결제를 거절했습니다 | — |
| CARD_LIMIT_EXCEEDED | 카드 이용 한도를 초과했습니다 | — |
| INSUFFICIENT_FUNDS | 결제 계좌의 잔액이 부족합니다 | — |
| MERCHANT_LIMIT_EXCEEDED | 결제 한도가 초과되었습니다. 잠시 후 다시 시도해 주세요 | — |
| PAYMENT_FAILED | 결제에 실패했습니다 | — |
| SUBSCRIPTION_PAST_DUE | 결제 실패 상태입니다 — 결제수단을 갱신해 주세요 | 전파 |
HTTP 403 — 권한 없음
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| ADMIN_ACTION_FORBIDDEN | 이 액션을 수행할 권한이 없습니다 | — |
| ADMIN_FORBIDDEN | 어드민 권한이 없습니다 | — |
| INTERNAL_PLAN_NOT_MUTABLE | 내부 전용 플랜은 콘솔에서 직접 변경/해지할 수 없습니다 | — |
| INTERNAL_PLAN_NOT_PURCHASABLE | 내부 전용 플랜으로는 변경할 수 없습니다 | — |
| WORKSPACE_ACCESS_DENIED | 해당 워크스페이스에 접근 권한이 없습니다 | — |
HTTP 404 — 리소스를 찾을 수 없음
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| ACCOUNT_NOT_FOUND | 계정을 찾을 수 없습니다 | — |
| ACTION_NOT_FOUND | 액션을 찾을 수 없습니다 | — |
| AGENT_BUG_REPORT_NOT_FOUND | 버그 제보를 찾을 수 없습니다 | — |
| API_KEY_NOT_FOUND | API 키를 찾을 수 없습니다 | — |
| CREDENTIAL_NOT_FOUND | 자격증명을 찾을 수 없습니다 | — |
| DATA_JOB_NOT_FOUND | 수집 요청을 찾을 수 없습니다 | — |
| INVOICE_NOT_FOUND | 청구서를 찾을 수 없습니다 | — |
| PARTNER_NOT_FOUND | 파트너를 찾을 수 없습니다 | — |
| PAYMENT_METHOD_NOT_FOUND | 결제수단을 찾을 수 없습니다 | — |
| RESOURCE_NOT_FOUND | 요청한 리소스를 찾을 수 없습니다 | — |
| SEO_AUDIT_EVENT_NOT_FOUND | SEO 이벤트를 찾을 수 없습니다 | — |
| SEO_TARGET_NOT_FOUND | SEO 모니터링 대상을 찾을 수 없습니다 | — |
| SUBSCRIPTION_NOT_FOUND | 구독 정보를 찾을 수 없습니다 | — |
| USER_CODE_INVALID | 유효하지 않은 인증 코드입니다. 다시 확인해 주세요 | — |
| WORKSPACE_MEMBER_NOT_FOUND | 워크스페이스 멤버를 찾을 수 없습니다 | — |
| WORKSPACE_NOT_FOUND | 워크스페이스를 찾을 수 없습니다 | — |
HTTP 405 — 기타
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| METHOD_NOT_ALLOWED | 허용되지 않은 HTTP 메서드입니다 | — |
HTTP 409 — 충돌·중복
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| CREDENTIAL_ALREADY_EXISTS | 이미 등록된 자격증명입니다 | — |
| CREDENTIAL_PROVIDER_DUPLICATED | 이 기관에 이미 등록된 자격증명이 있습니다. 갱신하려면 기존 자격증명에서 값을 변경하세요 | — |
| DUPLICATE_EMAIL | 이미 등록된 이메일입니다 | — |
| PAYMENT_METHOD_IN_USE | 활성 구독에서 사용 중인 결제수단입니다 | — |
HTTP 410 — 만료됨
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| USER_CODE_EXPIRED | 만료된 인증 코드입니다. CLI 에서 새 코드를 발급해 주세요 | — |
HTTP 415 — 기타
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| UNSUPPORTED_MEDIA_TYPE | 지원하지 않는 Content-Type 입니다 | — |
HTTP 422 — 기타
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| CERT_BIZNO_MISMATCH | 워크스페이스 사업자번호와 인증서가 일치하지 않습니다 | 전파 |
| CERT_ENCRYPTION_UNSUPPORTED | 지원하지 않는 인증서 암호화 알고리즘입니다 — 다른 형식의 공동인증서로 다시 시도해 주세요 | 전파 |
| CERT_EXPIRED | 인증서가 만료되었습니다 | 전파 |
| CERT_INVALID | 인증서 파일을 읽을 수 없습니다 | 전파 |
| CERT_KEY_USAGE_INVALID | 암호화 전용 인증서는 사용할 수 없습니다 — 서명용 인증서를 등록해 주세요 | 전파 |
| CERT_R_VALUE_NOT_FOUND | 인증서 형식이 올바르지 않습니다 — 사업자번호 확인에 실패했습니다 | 전파 |
| CERT_TYPE_UNSUPPORTED | 지원하지 않는 인증서 유형입니다 — 사업자/법인용 공동인증서를 등록해 주세요 | 전파 |
| CERT_WRONG_PASSWORD | 인증서 비밀번호가 올바르지 않습니다 | 전파 |
| CREDENTIAL_INSUFFICIENT_FOR_PROVIDER | 이 기관 자격증명을 먼저 등록해 주세요 | — |
| CREDENTIAL_PROBE_FAILED | 외부 기관 인증에 실패했습니다 — 입력값을 확인해 주세요 | 전파 |
| CREDENTIAL_SCOPE_NOT_SUPPORTED | 이 endpoint 는 기관 지정 자격증명만 지원합니다 — 공동인증서는 별도 endpoint 를 이용해 주세요 | — |
HTTP 429 — 한도 초과 — Retry-After 헤더 참고
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| API_RATE_LIMITED | API 호출 한도를 초과했습니다. 잠시 후 다시 시도해 주세요 | — |
| FREE_PLAN_JOB_CAP_REACHED | 무료 한도(월 수집 요청 수)에 도달했습니다 — 스탠다드 1x로 업그레이드 시 무제한 | — |
| FREE_PLAN_TASK_CAP_REACHED | 무료 한도(월 스크래핑 단계 수)에 도달했습니다 — 스탠다드 1x로 업그레이드 시 무제한 | — |
| TOO_MANY_CONCURRENT_WORKERS | 동시 처리 한도에 도달했습니다. 잠시 후 다시 시도해주세요 | — |
| TOO_MANY_LOGIN_ATTEMPTS | 로그인 시도가 너무 많습니다. 잠시 후 다시 시도해주세요 | — |
HTTP 500 — 서버 오류
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| ADMIN_ACTION_NOT_MARKED | 어드민 액션 엔드포인트에 권한 마킹이 누락되었습니다 | 전파 |
| INTERNAL_ERROR | 서버 내부 오류가 발생했습니다 | 전파 |
| SCRAPING_PARSER_NOT_FOUND | 스크래핑 응답 파서를 찾을 수 없습니다 | 전파 |
| SCRAPING_RESPONSE_MALFORMED | 스크래핑 응답 형식이 올바르지 않습니다 | 전파 |
HTTP 503 — 일시적 불가
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| SCRAPING_ENGINE_UNAVAILABLE | 스크래핑 엔진에 연결할 수 없습니다 | 전파 |