200이 아닌 HTTP 상태와 오류 본문을 돌려줍니다. 오류 응답은 과금되지 않습니다. 호출 기록은 남고, 체험(Trial) 프로젝트에서는 월 호출 수에 포함됩니다.
오류 응답 형식
응답 헤더
X-Tx-Id는 본문을 읽기 전에 거절된 요청(깨진 JSON 400 REQUEST_INVALID, 본문 크기 초과 413 REQUEST_TOO_LARGE)에는 없습니다. 문의할 때는 X-Tx-Id와 함께 X-Request-Id·X-Trace-Id도 알려 주세요.
오류 코드
요청 문제 (4xx)
요청을 고치기 전에는 같은 결과가 나옵니다. 그대로 재시도하지 마세요.입력 이미지 문제 (502)
엔진은 정상으로 답했지만 보낸 이미지에서 읽을 것을 찾지 못한 경우입니다. 같은 이미지를 다시 보내도 결과가 같으므로, 다시 촬영한 이미지로 호출하세요.서버·기관 문제 (5xx)
보내신 요청의 문제가 아닙니다. 아래 기준으로 재시도하세요.같은
v1 안에서도 오류 코드는 늘어날 수 있습니다. 모르는 code를 받으면 HTTP 상태(4xx·5xx)를 기준으로 처리하세요.중복 호출과 재시도
Unit API는 멱등 키를 받지 않습니다. 같은 요청을 두 번 보내면 두 건으로 처리하고 두 번 과금합니다.- 응답을 받지 못했거나
504 UPSTREAM_TIMEOUT을 받은 호출도 처리됐을 수 있습니다. 그대로 재시도하기 전에 대시보드 호출 내역에서 그 호출이 있는지 확인하세요.X-Tx-Id헤더를 받았다면 TX ID로 검색합니다.- 받지 못했다면 호출 내역 CSV의
referenceId열에서 찾습니다. 그러려면 호출마다 다른referenceId를 보내야 합니다.
- 5xx 재시도는 간격을 늘려 가며 3회 정도로 제한하세요. 예: 1초, 2초, 4초 후
- 체험 프로젝트는 오류 호출도 월 한도에 포함되므로 재시도 횟수를 더 엄격히 제한하세요.
응답 시간
기관 조회는 기관 응답을 기다리므로 수 초가 걸릴 수 있습니다. 예를 들어 운전면허증 진위확인은 5~12초 걸리는 경우가 있습니다. 클라이언트 타임아웃은 넉넉히(60초 이상) 두세요. 타임아웃을 짧게 잡으면 처리된 호출을 실패로 보고 재시도해 두 번 과금될 수 있습니다.버전 정책
경로의v1이 계약의 버전입니다.
같은 버전에서 적용되는 변경: 모르는 값을 만나도 실패하지 않게 구현하세요.
- API 추가, 선택 요청 필드 추가, 응답 필드 추가
- 필수 요청 필드가 선택으로 바뀌는 것
- enum 값 추가, 오류
code추가,message문구 개선
v1을 덮어쓰지 않습니다.
- API 제거, 경로·메서드 변경
- 필수 요청 필드 추가, 선택 필드가 필수로 바뀌는 것
- 응답 필드 삭제·이름 변경, enum 값이나 오류
code의 삭제·이름·의미 변경 - 필드 타입·
null허용 규칙·성공 조건·HTTP 상태 변경
agency, data.raw처럼 “계약으로 보장하지 않는다”고 적힌 필드는 이 정책의 대상이 아닙니다. 기관·엔진이 바꾸면 예고 없이 달라집니다.
문의할 때
아래 값을 함께 보내 주세요.- TX ID (
txId또는X-Tx-Id) X-Request-Id,X-Trace-Id- 호출 시각(UTC)과 호출한 API
- 받은 HTTP 상태와
code