에러 코드

전자(세금)계산서 발행 API

상태 코드	에러 코드	에러 메시지
`400`	`NOT_FOUND_CERTIFICATE`	공동인증서가 등록되지 않았습니다.
`400`	`INVALID_TRUSTEE_BUSINESS`	유효하지 않은 수탁자 사업자등록번호입니다.
`400`	`INVALID_SUPPLIER_BUSINESS`	현재 API 키에 등록된 발급자를 찾을 수 없습니다.

전자(세금)계산서 발행 웹훅

에러 코드	에러 메시지
`INVALID_SUPPLIER_BUSINESS`	공급자 사업자등록번호가 유효하지 않습니다. (미등록, 폐업)
`INVALID_SUPPLIED_BUSINESS`	공급받는자 사업자등록번호가 유효하지 않습니다.
`INVALID_TRUSTEE_BUSINESS`	수탁자 사업자등록번호가 유효하지 않습니다. (미등록, 폐업)
`INTERNAL_SERVER_ERROR`	볼타 서버에서 에러가 발생했습니다.
`INVALID_CERTIFICATE`	등록된 공동인증서가 유효하지 않습니다.(만료/폐기)

발급자 등록 API

상태 코드	에러 코드	에러 메시지
`400`	`INVALID_SUPPLIER_BUSINESS`	유효하지 않은 사업자등록번호입니다.

현금영수증 API

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	요청 검증 또는 취소 가능 상태 검증 실패
`401`	-	API 키 인증 실패. 응답 본문 없음
`403`	`FORBIDDEN`	발급자 접근 권한 없음
`409`	`IDEMPOTENCY_CONFLICT`	같은 `Bolta-Client-Reference-Id`에 다른 요청 내용
`409`	`CANCELLATION_ALREADY_REQUESTED`	같은 원본에 진행 중이거나 완료된 취소 요청이 있음
`409`	`ORIGINAL_ISSUANCE_PENDING`	원본 발행 요청이 아직 `PENDING` 상태라 취소할 수 없음
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`SERVICE_UNAVAILABLE`	발행이나 취소 중 내부 API 통신 오류

현금영수증 웹훅

현금영수증 발행이나 취소가 실패하면 API가 다음 코드를 웹훅 페이로드의 data.cause.code와 상태 조회 응답의 failure.code에 담습니다.

에러 코드	에러 메시지
`INVALID_ISSUER`	공급자 정보 또는 현금영수증 발행 등록 상태를 확인해주세요.
`INVALID_RECIPIENT_IDENTIFIER`	현금영수증 발급 수단 정보를 확인해주세요.
`ORIGINAL_ISSUANCE_FAILED`	원본 현금영수증 발행이 실패해 취소 요청을 처리할 수 없습니다.
`CANCELLATION_TARGET_NOT_FOUND`	이미 취소되었거나 취소할 수 없는 거래입니다.
`UNKNOWN`	현금영수증 처리에 실패했습니다. 문제가 계속되면 고객센터로 문의해주세요.

ORIGINAL_ISSUANCE_FAILED와 CANCELLATION_TARGET_NOT_FOUND는 CASH_RECEIPT_CANCEL_FAILED에서만 반환됩니다.

ORIGINAL_ISSUANCE_FAILED: 원본 발행이 처리 중일 때 취소 요청을 접수했지만, 이후 원본 발행이 최종 실패한 경우
CANCELLATION_TARGET_NOT_FOUND: 취소 대상이 확인되지 않거나 이미 취소된 경우. 볼타 외부(예: 홈택스)에서 전액이나 일부가 먼저 취소된 경우, 같은 현금영수증의 취소 요청이 이미 접수된 경우도 해당합니다

세금계산서 발행 마감일 조회 API

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	`date` 누락, `YYYY-MM-DD` 형식이 아니거나 존재하지 않는 날짜, 마감일을 제공하지 않는 달
`401`	-	API 키 인증 실패. 응답 본문 없음

세금계산서 발행 마감일 조회를 참고하세요.

사업자등록 상태 조회 API

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	사업자등록번호 누락, 10자리가 아닌 입력, 테스트 키의 안내 목록 밖 번호 조회. 일괄 조회의 빈 배열, 100개 초과
`400`	`INVALID_BUSINESS_REGISTRATION_NUMBER`	체크섬이 맞지 않는 사업자등록번호
`401`	-	API 키 인증 실패. 응답 본문 없음
`402`	`PAYMENT_REQUIRED`	포인트 잔액 부족
`403`	`FORBIDDEN`	리소스 접근 권한 없음
`409`	`AVAILABLE_POINTS_INSUFFICIENT`	진행 중인 다른 요청 때문에 지금 쓸 수 있는 포인트 부족
`429`	`RATE_LIMITED`	파트너 호출 한도 또는 볼타 서비스 전체 조회 한도 초과. `Retry-After` 헤더에 재시도까지 남은 초를 담습니다
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`LOOKUP_UNAVAILABLE`	사업자등록 상태를 확인할 수 없음. 일괄 조회는 한 건도 확인하지 못한 경우
`503`	`SERVICE_UNAVAILABLE`	일시적인 내부 API 통신 오류

일괄 조회에서 일부 번호만 확인하지 못하면 오류 대신 200으로 응답하고 해당 항목의 status를 null로 둡니다. 사업자등록 상태 조회를 참고하세요.

사업자등록증 인식과 진위확인 API

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	`file` 파트 누락, 빈 파일, 5MB 초과
`400`	`INVALID_FILE`	지원하지 않는 형식, 읽을 수 없는 파일, 5쪽 초과 PDF, 사업자등록증이 아니거나 사업자등록번호를 읽을 수 없는 파일
`401`	-	API 키 인증 실패. 응답 본문 없음
`402`	`PAYMENT_REQUIRED`	포인트 잔액 부족
`409`	`AVAILABLE_POINTS_INSUFFICIENT`	진행 중인 다른 요청 때문에 지금 쓸 수 있는 포인트 부족
`415`	`UNSUPPORTED_MEDIA_TYPE`	`Content-Type`이 `multipart/form-data`가 아님
`429`	`TOO_MANY_IN_FLIGHT`	같은 파트너의 처리 중인 요청이 있음. 라이브 키만 해당. `Retry-After` 헤더에 재시도까지 남은 초를 담습니다
`429`	`RATE_LIMITED`	하루 처리 한도 초과 또는 볼타 인식 처리량 포화. `Retry-After` 헤더에 재시도까지 남은 초를 담습니다
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`EXTRACTION_UNAVAILABLE`	인식 실패 또는 처리 시간 초과
`503`	`LOOKUP_UNAVAILABLE`	호출 한도를 판정할 수 없음
`503`	`SERVICE_UNAVAILABLE`	일시적인 내부 API 통신 오류

사업자등록증 인식과 진위확인을 참고하세요.

매출/매입 내역 조회 API

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	날짜 형식 오류, `from`이 `to`보다 늦음, `type`이나 `limit` 값 오류
`400`	`INVALID_CURSOR`	변조했거나 형식이 틀린 cursor, 경로나 조건이나 키 모드가 cursor를 받을 때와 다름
`401`	-	API 키 인증 실패. 응답 본문 없음
`402`	`PLAN_UPGRADE_REQUIRED`	스탠다드 플랜 미만 (포인트 잔액 부족과 다름)
`409`	`SYNC_IN_PROGRESS`	같은 경로의 수집이 이미 진행 중
`422`	`NO_SOURCE_CONNECTED`	매출이나 매입을 가져올 연동이 없음
`429`	`SYNC_RATE_LIMITED`	동기화 요청 한도 초과. `Retry-After` 헤더에 재시도까지 남은 초를 담습니다
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`FEED_UNAVAILABLE`	일시적으로 내역을 불러올 수 없음. 같은 cursor로 다시 호출하세요
`503`	`SYNC_UNAVAILABLE`	동기화 요청을 일시적으로 판정할 수 없음
`503`	`SERVICE_UNAVAILABLE`	일시적인 내부 API 통신 오류

매출/매입 내역 조회를 참고하세요.

입출금 내역 조회 API

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	날짜 형식 오류, `from`이 `to`보다 늦음, `transactionType`이나 `limit` 값 오류
`400`	`INVALID_CURSOR`	변조했거나 형식이 틀린 cursor, 조건이나 API 키가 cursor를 받을 때와 다름
`401`	-	API 키 인증 실패. 응답 본문 없음
`402`	`PLAN_UPGRADE_REQUIRED`	스탠다드 플랜 미만 (포인트 잔액 부족과 다름)
`404`	`BANK_ACCOUNT_NOT_FOUND`	없거나 내 사업자의 것이 아닌 `bankAccountId`
`409`	`SYNC_IN_PROGRESS`	동기화가 이미 진행 중
`422`	`BANK_ACCOUNT_NOT_CONNECTED`	연결된 입출금 계좌가 없음
`429`	`SYNC_RATE_LIMITED`	동기화 요청 한도 초과. `Retry-After` 헤더에 재시도까지 남은 초를 담습니다
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`SYNC_UNAVAILABLE`	동기화 요청을 일시적으로 판정할 수 없음
`503`	`SERVICE_UNAVAILABLE`	일시적인 내부 API 통신 오류

입출금 내역 조회를 참고하세요.

예금주 조회 API

예금주를 찾지 못하면 단건 조회는 HTTP 400으로 응답하고, 일괄 조회는 HTTP 200 응답의 results[].error에 오류를 담습니다.

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	요청 형식 오류, 계좌 100개 초과, 테스트 키로 안내 목록 밖 계좌 조회
`400`	`ACCOUNT_NOT_VERIFIED`	계좌를 확인하지 못함
`400`	`ACCOUNT_NOT_AVAILABLE`	입금이 정지된 가상계좌
`400`	`AMOUNT_REQUIRED`	입금 금액이 정해진 가상계좌인데 `amount`가 없음
`400`	`AMOUNT_MISMATCH`	입력한 `amount`가 가상계좌에 정해진 금액과 다름
`400`	`AMOUNT_VERIFICATION_UNAVAILABLE`	금액 지정형 가상계좌를 지금은 조회할 수 없음
`400`	`UNSUPPORTED_BANK`	예금주 조회를 지원하지 않는 은행코드
`401`	-	API 키 인증 실패. 응답 본문 없음
`402`	`PAYMENT_REQUIRED`	포인트 잔액 부족
`403`	`FORBIDDEN`	접근 권한 없음
`409`	`AVAILABLE_POINTS_INSUFFICIENT`	진행 중인 다른 요청 때문에 지금 쓸 수 있는 포인트 부족
`429`	`RATE_LIMITED`	하루 조회 한도 초과. `Retry-After` 헤더에 재시도까지 남은 초를 담습니다
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`BANK_UNAVAILABLE`	은행 점검이나 연결 오류
`503`	`LOOKUP_UNAVAILABLE`	조회 보호 한도를 판정할 수 없음
`503`	`SERVICE_UNAVAILABLE`	일시적인 내부 API 통신 오류

예금주 조회를 참고하세요.

서류 발급 API

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	요청 형식 오류, 사업자등록증명의 `language` 누락, 법인등록번호 형식 오류, 법인등기의 `cancelledEntries` 누락, 테스트 키로 안내 목록 밖 법인등록번호 요청
`400`	`PERIOD_NOT_CLOSED`	표준재무제표증명의 사업연도가 끝나지 않음
`401`	-	API 키 인증 실패. 응답 본문 없음
`402`	`PAYMENT_REQUIRED`	포인트 잔액 부족
`404`	`DOCUMENT_ISSUANCE_NOT_FOUND`	없는 `issuanceKey`, 다른 파트너나 다른 모드 키로 접수한 요청
`409`	`CERTIFICATE_REQUIRED`	공동인증서 미등록 또는 만료. 홈택스 서류만 해당
`409`	`IDEMPOTENCY_CONFLICT`	같은 `Bolta-Client-Reference-Id`에 다른 본문
`409`	`OUTSIDE_SERVICE_HOURS`	서류의 요청 가능 시간 밖 요청
`409`	`TARGET_BUSY`	같은 법인, 같은 등기 서류, 같은 `cancelledEntries`를 다른 요청이 발급 중
`409`	`AVAILABLE_POINTS_INSUFFICIENT`	진행 중인 다른 요청 때문에 지금 쓸 수 있는 포인트 부족
`429`	`TOO_MANY_IN_FLIGHT`	처리 중인 요청이 5건
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`DOCUMENT_ISSUANCE_UNAVAILABLE`	지금은 발급할 수 없음. 잠시 후 다시 요청
`503`	`SERVICE_UNAVAILABLE`	일시적인 내부 API 통신 오류

서류 발급을 참고하세요.

세금계산서 PDF 조회 API

상태 코드	에러 코드	발생 조건
`400`	`TAX_INVOICE_RETRIEVE_NOT_AVAILABLE`	발행 완료 전이거나 발행 실패. 역발행은 공급자 승인 전이거나 거절
`400`	`INVALID_DOCUMENT`	볼타에 저장된 문서 정보로 PDF를 만들 수 없음
`401`	-	API 키 인증 실패. 응답 본문 없음
`403`	`FORBIDDEN`	발행을 요청한 API 키가 아님
`404`	`NOT_FOUND`	없는 `issuanceKey`
`429`	`TOO_MANY_IN_FLIGHT`	같은 사업자에서 만드는 중인 PDF 10건 또는 같은 API 키로 만드는 중인 PDF 20건
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`PDF_GENERATION_FAILED`	여러 번 시도했지만 PDF를 만들지 못함
`503`	`SERVICE_UNAVAILABLE`	일시적인 내부 API 통신 오류

자세한 내용은 세금계산서 PDF 조회를 참고하세요.

공통 에러

상태 코드	에러 코드	에러 메시지
`400`	`INVALID_REQUEST`	요청을 처리할 수 없습니다. 필수 파라미터를 보내지 않았거나, 파라미터 포맷이 잘못되었을 때 돌아오는 응답입니다. 요청 파라미터를 확인해주세요.
`404`	`NOT_FOUND`	요청한 리소스가 존재하지 않습니다. 요청한 API 주소를 다시 한 번 확인해주세요.
`500`	`INTERNAL_SERVER_ERROR`	볼타 서버에서 에러가 발생했습니다.

API 소개

API 가이드

사용 사례

SDK/노코드 연동

전자(세금)계산서 발행 API

전자(세금)계산서 발행 웹훅

발급자 등록 API

현금영수증 API

현금영수증 웹훅

세금계산서 발행 마감일 조회 API

사업자등록 상태 조회 API

사업자등록증 인식과 진위확인 API

매출/매입 내역 조회 API

입출금 내역 조회 API

예금주 조회 API

서류 발급 API

세금계산서 PDF 조회 API

공통 에러

​전자(세금)계산서 발행 API

​전자(세금)계산서 발행 웹훅

​발급자 등록 API

​현금영수증 API

​현금영수증 웹훅

​세금계산서 발행 마감일 조회 API

​사업자등록 상태 조회 API

​사업자등록증 인식과 진위확인 API

​매출/매입 내역 조회 API

​입출금 내역 조회 API

​예금주 조회 API

​서류 발급 API

​세금계산서 PDF 조회 API

​공통 에러

전자(세금)계산서 발행 API

전자(세금)계산서 발행 웹훅

발급자 등록 API

현금영수증 API

현금영수증 웹훅

세금계산서 발행 마감일 조회 API

사업자등록 상태 조회 API

사업자등록증 인식과 진위확인 API

매출/매입 내역 조회 API

입출금 내역 조회 API

예금주 조회 API

서류 발급 API

세금계산서 PDF 조회 API

공통 에러