에러 안내
API 에러 코드 참조 가이드
API 호출 시 발생할 수 있는 에러 코드와 해결 방법을 안내합니다.
에러 코드 분류
클라이언트의 요청에 문제가 있을 때 발생하는 에러입니다.
400 Bad Request - 요청 오류
요청 형식이나 파라미터에 문제가 있을 때 발생합니다.
| 에러 메시지 | 설명 | 해결방법 |
|---|---|---|
| Bad request | 요청이 올바르지 않음 | API 문서의 요청 형식을 확인하세요 |
| Validation failed | 요청이 올바르지 않음 | 필수 파라미터와 데이터 타입을 검토하세요 |
| Position must have either (x, y, page) or anchor, not both or neither | 필드 위치 지정 방식이 올바르지 않음 | 좌표(x, y, page) 또는 anchor 중 하나만 사용. 동시 지정 또는 둘 다 미지정 불가 |
| Participants's signing order must be all 1, or sequential | 서명 순서는 모두 1이거나, 순차적 이어야함 | 서명 순서를 1 또는 1,2,3... 형태로 수정 |
| All participants's role must be unique | 모든 참여자의 역할은 중복되지 않아야함 | 각 참여자에게 서로 다른 역할 부여 |
| api-key and authorization header cannot be used | 인증방식 중복을 허용하지 않음 | API 키 또는 Authorization 헤더 중 하나만 사용 |
| The number of image request input must not exceed 5 | 이미지 파일은 5개를 초과할 수 없음 | 이미지 파일 개수를 5개 이하로 제한 |
| metadatas must contain no more than 10 elements | 메타데이터는 10개를 초과할 수 없음 | 메타데이터 개수를 10개 이하로 제한 |
| phoneNumber must maatch /^01([0\|1\|6\|7\|8\|9])([0-9]4)([0-9]4)$/ regular expression | 전화번호 형식이 올바르지 않음 | 올바른 한국 휴대폰 번호 형식으로 입력 (예: 01012345678) |
| font must be one of the following values: NOTO_SANS, NOTO_SERIF | 지원하지 않는 폰트 사용 | NOTO_SANS 또는 NOTO_SERIF 중 선택하여 사용 |
401 Unauthorized - 인증 실패
API 키나 인증 정보에 문제가 있을 때 발생합니다.
| 에러 메시지 | 해결방법 |
|---|---|
| Unauthorized | • API 키가 올바른지 확인 • Authorization: Bearer YOUR_API_KEY 헤더 포함 |
403 Forbidden - 권한 없음
요청에 대한 권한이나 사용량 제한에 문제가 있을 때 발생합니다.
| 에러 메시지 | 설명 | 해결방법 |
|---|---|---|
| Usage limit exceeded | API 사용량이 모두 소진됨 | 사용량 한도 확인 또는 플랜 업그레이드 |
| Forbidden | 권한이 없음 | 해당 리소스에 대한 접근 권한 확인 |
404 Not Found
요청한 리소스를 찾을 수 없을 때 발생합니다.
| 에러 메시지 | 설명 | 해결방법 |
|---|---|---|
| Not found | 요청한 리소스를 찾을 수 없음 | • 요청 URL이 올바른지 확인 • 문서 ID나 리소스 ID가 존재하는지 확인 |
| Anchor text not found in PDF | Anchor 텍스트가 문서 내에 존재하지 않음 (AnchorTextNotFoundException) | • anchor.text 값과 문서 내 텍스트가 정확히 일치하는지 확인 (대소문자, 공백, 특수문자 포함)• 스캔된 이미지 PDF인 경우 OCR 처리된 PDF 사용 • PDF 폰트 임베딩 이슈로 텍스트가 깨지지 않았는지 확인 |
요청은 올바르지만 비즈니스 로직상 처리할 수 없을 때 발생하는 에러입니다.
문서 및 참여자 관련
| 에러 메시지 | 설명 | 해결방법 |
|---|---|---|
| Unprocessable entity | 진행할 수 없는 대상 | 요청 데이터와 비즈니스 규칙 확인 |
| Document status is invalid | 문서의 상태가 올바르지 않음 | 문서 상태가 ON_GOING인지 확인 (서명요청 취소 시) |
| Participant name is required | 참여자의 이름이 없음 | 모든 참여자에게 이름 필드 추가 |
| Participant's signingMethod is required | 참여자의 서명수단이 없음 | EMAIL 또는 KAKAO 중 선택하여 입력 |
| Participant role is not matched | 해당 역할을 찾을 수 없음 | 템플릿에 정의된 역할과 일치하는지 확인 |
| All participants are excluded | 모든 참여자가 제외 | 최소 1명 이상의 참여자 포함 |
입력값 및 데이터 검증
| 에러 메시지 | 설명 | 해결방법 |
|---|---|---|
| Requester input value is invalid | 추가 내용 입력의 value가 타입에 맞지 않음 | • TEXT 타입: string 값 사용• CHECKBOX 타입: boolean 값 사용 |
| Cannot map to signer field | 서명자 입력값을 잘못된 곳에 추가함 | 추가 내용 입력란에서 서명자 입력란 제외 |
| Data label of requester input is not matched | 일치하는 데이터라벨 정보 없음 | 템플릿의 데이터 라벨과 요청 데이터 일치 확인 |
| Data label of attachment request is not matched | 일치하는 데이터라벨 정보 없음 | 첨부파일 요청의 데이터 라벨 확인 |
| Requester input custom id is not matched | 추가내용 입력의 customId를 템플릿에서 찾을 수 없음 | 템플릿에 정의된 customId 사용 |
파일 및 제한사항
| 에러 메시지 | 설명 | 해결방법 |
|---|---|---|
| Max attachment count is exceeded | 문서의 최대 첨부파일 수 초과 | 첨부파일을 20개 이하로 제한 |
| Max signature field count is exceeded | 문서의 최대 사인도장 입력란 수 초과 | 사인도장 입력란을 30개 이하로 제한 |
| This file is invalid | 파일이 유효하지 않음 | • PNG, JPG 확장자 사용 • 올바른 base64 인코딩 값 확인 |
| Image file is broken | 이미지 파일이 부정확함 | 이미지 파일 재업로드 또는 다른 파일 사용 |
| SigningMethod type is invalid | 사인방법이 올바르지 않음 | EMAIL 또는 KAKAO만 사용 가능 |
서명 기능 관련
| 에러 메시지 | 설명 | 해결방법 |
|---|---|---|
| Signature field is required | 템플릿의 참여자에 사인도장 입력란이 지정되지 않음 | 각 참여자에게 최소 1개의 사인도장 입력란 추가 |
| This document was created before the implementation | 서명 내용 수정 요청 기능이 지원되기 전에 생성된 문서 | 새 문서로 다시 생성하거나 기존 방식 사용 |
| The order of signer must not be duplicated | 서명 내용 수정 기능에는 순서 없는 서명 지원 안함 | 서명 순서를 명확히 지정 |
기타
| 에러 메시지 | 설명 | 해결방법 |
|---|---|---|
| User already exists | 해당 사용자는 이미 존재함 | 다른 사용자 정보 사용 또는 기존 사용자 활용 |
| Verification type is duplicated | 같은 종류의 인증을 2개 이상 가질 수 없음 | 인증 타입을 중복되지 않게 설정 |
서버 내부에서 문제가 발생했을 때 나타나는 에러입니다.
| 코드 | 에러 메시지 | 설명 | 해결방법 |
|---|---|---|---|
| 500 | Internal server error | 알 수 없는 서버 에러 | 잠시 후 재시도, 지속 시 기술지원팀 문의 |
문제 해결 체크리스트
문제가 지속될 때 다음 순서로 확인해보세요:
1. API 키 확인
올바른 키와 권한 설정이 되어있는지 확인
2. 요청 형식 검증
JSON 구조와 필수 파라미터가 올바른지 확인
3. 데이터 타입 확인
string, boolean, number 등 타입이 정확한지 확인
4. 용량 제한 확인
파일 개수, 메타데이터 개수 등 제한사항 확인
5. 문서 상태 확인
현재 문서가 요청 가능한 상태인지 확인
기술지원 문의 가이드
API 호출 오류 발생 시, 아래 정보 모두 전달해 주시면 확인 후 안내드리겠습니다.[필수 정보]
- API 호출 시 사용 이메일
- 사용한 API (템플릿 서명요청 등)
- 오류 발생 시간 (년-월-일 시:분 형식)
- 에러 로그 (응답받은 전체 에러 메시지)
[선택 정보]
- 요청 본문 (민감정보 마스킹 후)
이 정보들을 제공해주시면 더 빠르고 정확한 기술지원을 받으실 수 있습니다.
Updated 5 months ago
Did this page help you?