// data catalog / errors
에러 코드
모든 에러 응답은 {"code": "...", "message": "...", "requestId": "..."} 구조입니다. 검증 실패 시에는 fieldErrors 배열이 함께 포함됩니다. code 는 정규화된 enum 이라 자동화 분기에 안전하게 쓸 수 있습니다.
HTTP 400 (요청 형식·값 오류)
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| ACTION_NOT_SUPPORTED | 해당 프로바이더에서 지원하지 않는 액션입니다 | - |
| ALREADY_FREE_NO_OP | 이미 FREE 플랜이라 해지할 수 없습니다 | - |
| API_KEY_ALREADY_REVOKED | 이미 폐기된 API 키입니다. 콘솔에서 새 키를 발급해 주세요 | - |
| CONNECTION_AND_CREDENTIAL_ID_EXCLUSIVE | connectionId 와 credentialId 는 동시에 지정할 수 없습니다 — 하나만 사용해 주세요 | - |
| CONNECTION_NOT_ALLOWED_FOR_NON_PARTNER | connection 은 파트너 경로에서만 지원됩니다 | - |
| CONNECTION_REQUIRED_FOR_PARTNER | 파트너 경로에서는 connectionId 가 필요합니다 | - |
| CREDENTIAL_ID_NOT_ALLOWED | credentialId 는 이 경로에서 사용할 수 없습니다. connectionId 를 사용해 주세요 | - |
| CREDENTIAL_ID_NOT_ALLOWED_FOR_NON_PARTNER | credentialId 필드는 이 요청에서 지원되지 않습니다 — 필드를 제거하고 다시 시도해 주세요 | - |
| DATE_RANGE_EXCEEDED | 허용된 최대 조회 기간을 초과했습니다. 기간을 짧게 나눠 여러 요청으로 보내 주세요 | - |
| DATE_RANGE_INVALID | 조회 기간 범위가 유효하지 않습니다 | - |
| DELIVERY_ROUTE_NOT_FOUND | 해당 워크스페이스에 배달 경로가 설정되지 않았습니다. 콘솔의 워크스페이스 설정에서 배달 경로를 추가해 주세요 | - |
| DEVICE_CODE_EXPIRED | 만료된 device_code입니다. 다시 시도해 주세요 | - |
| DEVICE_CODE_INVALID | 유효하지 않은 device_code입니다. CLI에서 새 인증을 시작해 주세요 | - |
| INVALID_BUSINESS_REGISTRATION_NUMBER | 사업자등록번호 형식이 올바르지 않습니다 | - |
| INVALID_CREDENTIAL_FORMAT | 인증 필드 형식이 올바르지 않습니다. credential-schema 응답의 pattern 을 확인해 주세요 | - |
| INVALID_CURSOR | 유효하지 않은 커서입니다. 직전 응답의 nextCursor 값을 그대로 사용해 주세요 | - |
| INVALID_DATA_JOB_PARAMS | 요청 파라미터가 올바르지 않습니다 | - |
| INVALID_PARAM_FORMAT | 파라미터 형식이 올바르지 않습니다 | - |
| INVALID_PROVIDER_CODE | 지원하지 않는 프로바이더 코드입니다. GET /api/v1/providers 응답에서 사용 가능한 코드를 확인해 주세요 | - |
| INVALID_USAGE_CREDIT | 사용량 크레딧 값이 올바르지 않습니다 | - |
| MALFORMED_REQUEST | 요청 본문 형식이 올바르지 않습니다 | - |
| MISSING_CREDENTIAL_FIELD | 필수 인증 필드가 누락되었습니다. GET /api/v1/providers/{code}/credential-schema 응답의 fields를 확인해 주세요 | - |
| MISSING_PARAMETER | 필수 파라미터가 누락되었습니다 | - |
| MISSING_REQUIRED_PARAM | 필수 파라미터가 누락되었습니다 | - |
| NO_PENDING_PLAN_CHANGE | 취소할 예약된 플랜 변경이 없습니다 | - |
| PARTNER_BUSINESS_SELECTOR_REQUIRED | X-H6S-Business 헤더(사업자등록번호)가 필요합니다 | - |
| PARTNER_NAME_INVALID | 파트너 이름이 유효하지 않습니다 | - |
| PARTNER_WEBHOOK_URL_INVALID | 웹훅 URL 이 유효하지 않습니다 | - |
| PAYMENT_METHOD_REQUIRED | 결제수단을 먼저 등록해 주세요 | - |
| PROVIDER_CODE_MISMATCH | 요청한 기관과 자격증명에 묶인 기관이 다릅니다. providerCode 를 자격증명에 맞춰 주세요 | - |
| PROVIDER_CODE_REQUIRED_FOR_GLOBAL_CERT | 공동인증서 자격증명은 어느 기관으로 호출할지 함께 지정해야 합니다 | - |
| PROVIDER_DOES_NOT_ACCEPT_CERT_LOGIN | 이 기관은 공동인증서 로그인을 지원하지 않습니다. 기관 ID·비밀번호로 자격증명을 등록해 주세요 | - |
| REGISTRATION_E2E_DECRYPT_FAILED | 암호화된 자격증명을 복호화하지 못했습니다. 등록 페이지를 새로고침한 뒤 다시 시도해 주세요 | - |
| REGISTRATION_E2E_UNKNOWN_KEY_ID | 암호화에 사용한 키가 더 이상 유효하지 않습니다. 등록 페이지를 새로고침한 뒤 다시 시도해 주세요 | - |
| REGISTRATION_SESSION_INVALID_CLIENT_REFERENCE_ID | clientReferenceId 는 128자 이하의 문자열이어야 합니다 | - |
| REGISTRATION_SESSION_INVALID_ORIGIN | originAllowlist 항목은 scheme://host[:port] 형식이어야 합니다 (예: https://partner.example.com) | - |
| REGISTRATION_SESSION_INVALID_REGISTRATION_OPTIONS | registrationOptions 형식이 올바르지 않습니다. 공동인증서는 providerCode 없이, 기관 아이디는 providerCode 와 함께 지정해 주세요 | - |
| SAME_PLAN_CHANGE | 이미 같은 플랜입니다 | - |
| SUBSCRIPTION_NOT_PAST_DUE | 결제 실패 상태가 아닙니다 | - |
| UNSUPPORTED_AUTH_METHOD | 지원하지 않는 인증 방식입니다. GET /api/v1/providers/{code} 의 acceptedAuthMethods 를 확인해 주세요 | - |
| USAGE_CREDIT_EXPIRES_IN_PAST | 사용량 크레딧 만료일은 현재 시각보다 이후여야 합니다 | - |
| USAGE_CREDIT_NOT_APPLICABLE | 월간 사용량 한도가 없는 플랜에는 크레딧을 지급할 수 없습니다 | - |
HTTP 401 (인증 실패)
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| INVALID_CREDENTIALS | 이메일 또는 비밀번호가 올바르지 않습니다 | - |
| INVALID_TOKEN | 유효하지 않은 토큰입니다. 다시 로그인해 주세요 | - |
| REGISTRATION_SESSION_TOKEN_INVALID | 유효하지 않은 등록 세션 토큰입니다. 발급 파트너에 새 등록 링크를 요청해 주세요 | - |
| 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 | 내부 전용 플랜으로는 변경할 수 없습니다 | - |
| REGISTRATION_SESSION_BUSINESS_MISMATCH | 사업자번호가 세션 발급 시 지정한 값과 일치하지 않습니다. end-user 의 자격증명 사업자번호를 확인해 주세요 | - |
| REGISTRATION_SESSION_OPTION_NOT_ALLOWED | 이 세션이 허용하지 않는 등록 옵션입니다. 세션 발급 시 지정한 옵션 중 하나로 다시 시도해 주세요 | - |
| WORKSPACE_ACCESS_DENIED | 해당 워크스페이스에 접근 권한이 없습니다 | - |
HTTP 404 (리소스를 찾을 수 없음)
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| ACCOUNT_NOT_FOUND | 계정을 찾을 수 없습니다 | - |
| ACTION_NOT_FOUND | 액션을 찾을 수 없습니다 | - |
| AGENT_BUG_REPORT_NOT_FOUND | 버그 제보를 찾을 수 없습니다 | - |
| API_KEY_NOT_FOUND | API 키를 찾을 수 없습니다. 콘솔의 API 키 메뉴에서 발급 상태를 확인해 주세요 | - |
| CONNECTION_NOT_FOUND | connection 을 찾을 수 없습니다 | - |
| CREDENTIAL_NOT_FOUND | 자격증명을 찾을 수 없습니다. 콘솔의 자격증명 메뉴에서 추가해 주세요 | - |
| DATA_JOB_NOT_FOUND | 수집 요청을 찾을 수 없습니다. id를 다시 확인하거나 GET /data-jobs 로 목록을 조회해 주세요 | - |
| INVOICE_NOT_FOUND | 청구서를 찾을 수 없습니다 | - |
| PARTNER_NOT_FOUND | 파트너를 찾을 수 없습니다 | - |
| PAYMENT_METHOD_NOT_FOUND | 결제수단을 찾을 수 없습니다 | - |
| REGISTRATION_SESSION_NOT_FOUND | 등록 세션을 찾을 수 없습니다. 세션 ID 를 다시 확인하거나 새 세션을 발급해 주세요 | - |
| RESOURCE_NOT_FOUND | 요청한 리소스를 찾을 수 없습니다 | - |
| SCHEMA_NOT_FOUND | 데이터 형식을 찾을 수 없습니다. schema 를 다시 확인하거나 GET /schemas 로 사용 가능한 형식을 조회해 주세요 | - |
| SUBSCRIPTION_NOT_FOUND | 구독 정보를 찾을 수 없습니다 | - |
| USER_CODE_INVALID | 유효하지 않은 인증 코드입니다. 다시 확인해 주세요 | - |
| WORKSPACE_MEMBER_NOT_FOUND | 워크스페이스 멤버를 찾을 수 없습니다 | - |
| WORKSPACE_NOT_FOUND | 워크스페이스를 찾을 수 없습니다 | - |
HTTP 405 (기타)
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| METHOD_NOT_ALLOWED | 허용되지 않은 HTTP 메서드입니다 | - |
HTTP 409 (충돌·중복)
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| CONNECTION_REVOKED | 연결(connection)이 해제되어 더 이상 사용할 수 없습니다. 새 연결을 발급받아 다시 시도해 주세요 | - |
| CREDENTIAL_EXPIRED | 자격증명이 만료되었습니다. 자격증명을 다시 등록해 주세요 | - |
| CREDENTIAL_HAS_ACTIVE_CONNECTIONS | 활성 연결(connection)이 있어 자격증명을 삭제할 수 없습니다 — 먼저 연결을 해제(detach)해 주세요 | - |
| CREDENTIAL_NATIVE_REWRAP_IN_PROGRESS | 이미 인증서 포맷 변환 작업이 실행 중입니다. 잠시 후 다시 시도해 주세요 | - |
| CREDENTIAL_REVOKED | 자격증명이 폐기되었습니다. 자격증명을 다시 등록해 주세요 | - |
| CREDENTIAL_SUPERSEDED | 자격증명이 새 자격증명으로 교체되었습니다. 교체된 자격증명으로 다시 시도해 주세요 | - |
| DUPLICATE_EMAIL | 이미 등록된 이메일입니다. 로그인하거나 다른 이메일로 가입해 주세요 | - |
| PAYMENT_METHOD_IN_USE | 활성 구독에서 사용 중인 결제수단입니다. 다른 결제수단으로 교체한 뒤 다시 시도해 주세요 | - |
HTTP 410 (만료됨)
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| REGISTRATION_SESSION_ALREADY_CANCELLED | 취소된 등록 세션입니다. 다시 등록하려면 새 세션을 발급해 주세요 | - |
| REGISTRATION_SESSION_ALREADY_CONSUMED | 이미 사용된 등록 세션입니다. 새 자격증명이 필요하면 발급 파트너에서 새 세션을 받으세요 | - |
| REGISTRATION_SESSION_EXPIRED | 만료된 등록 세션입니다. 새 등록 링크를 요청해 주세요 | - |
| REGISTRATION_SESSION_MAX_ATTEMPTS_EXCEEDED | 입력 실패 횟수가 한도를 초과했습니다. 새 등록 링크를 요청해 주세요 | - |
| REGISTRATION_SESSION_NOT_USABLE | 이 등록 세션은 더 이상 사용할 수 없습니다. 새 등록 링크를 요청해 주세요 | - |
| USER_CODE_EXPIRED | 만료된 인증 코드입니다. CLI에서 새 코드를 발급해 주세요 | - |
HTTP 415 (기타)
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| UNSUPPORTED_MEDIA_TYPE | 지원하지 않는 Content-Type 입니다 | - |
HTTP 422 (기타)
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| CERT_BIZNO_MISMATCH | 워크스페이스 사업자번호와 인증서 사업자번호가 일치하지 않습니다. 워크스페이스 설정 또는 인증서를 다시 확인해 주세요 | 전파 |
| CERT_ENCRYPTION_UNSUPPORTED | 지원하지 않는 인증서 암호화 알고리즘입니다 — 다른 형식의 공동인증서로 다시 시도해 주세요 | 전파 |
| CERT_EXPIRED | 인증서가 만료되었습니다. 인증센터에서 재발급한 뒤 다시 등록해 주세요 | 전파 |
| CERT_INVALID | 인증서 파일을 읽을 수 없습니다. PFX 파일이 올바른지 확인해 주세요 | 전파 |
| CERT_KEY_PAIR_MISMATCH | 인증서와 개인키가 서로 맞지 않습니다 — 같은 인증서의 signCert.der 와 signPri.key 를 함께 등록해 주세요 | 전파 |
| CERT_KEY_USAGE_INVALID | 암호화 전용 인증서는 사용할 수 없습니다 — 서명용 인증서를 등록해 주세요 | 전파 |
| CERT_R_VALUE_NOT_FOUND | 인증서 형식이 올바르지 않습니다 — 사업자번호 확인에 실패했습니다 | 전파 |
| CERT_TYPE_UNSUPPORTED | 지원하지 않는 인증서 유형입니다. 사업자 또는 법인용 공동인증서를 등록해 주세요. | 전파 |
| CERT_WRONG_PASSWORD | 인증서 비밀번호가 올바르지 않습니다. PFX 비밀번호를 다시 확인해 주세요 | 전파 |
| 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로 업그레이드 시 무제한 | - |
| 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 (일시적 불가)
| 코드 | 메시지 | 운영 알림 |
|---|---|---|
| CERT_CRYPTO_UNAVAILABLE | 공동인증서 검증을 처리할 수 없습니다. 잠시 후 다시 시도해 주세요 | 전파 |
| SCRAPING_ENGINE_UNAVAILABLE | 스크래핑 엔진에 연결할 수 없습니다. 잠시 후 다시 시도해 주세요 | 전파 |