API 에러 코드 참조 가이드

API 호출 시 발생할 수 있는 에러 코드와 해결 방법을 안내합니다.

💡
빠른 해결 팁
대부분의 에러는 요청 형식이나 파라미터 문제로 발생하므로, 먼저 요청 데이터를 점검해보세요.

에러 코드 분류

상태 코드	구분	발생 상황
400	Bad Request - 요청 오류	요청 형식이나 파라미터에 문제가 있을 때 발생합니다.
401	Unauthorized - 인증 실패	API 키나 인증 정보에 문제가 있을 때 발생합니다.
403	Forbidden - 권한 없음	요청에 대한 권한이나 사용량 제한에 문제가 있을 때 발생합니다.
404	Not Found	요청한 리소스를 찾을 수 없을 때 발생합니다.
422	처리 불가 에러	요청은 올바르지만 비즈니스 로직상 처리할 수 없을 때 발생하는 에러입니다.
5xx	서버 에러	서버 내부에서 문제가 발생했을 때 나타나는 에러입니다.

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]{3,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`	권한이 없음	해당 리소스에 대한 접근 권한 확인 권한 부여 직후라면 잠시 후 재시도 (아래 안내 참고)

🚧
권한 부여 직후 일시적으로 403이 응답될 수 있습니다
요청을 처리하면서 생성되는 리소스에 대한 권한을 처리하는 과정에서 짧은 지연이 발생할 수 있습니다.
따라서 권한이 반영되기 전까지는 후속 요청이 403 Forbidden으로 실패할 수 있습니다.
예시:

요금제 구독 시작 직후 서명 요청 등 요금제 권한이 필요한 API를 호출하는 경우

리소스 생성 직후 해당 리소스를 조회하거나 수정하는 경우

위와 같은 경우에는 일시적인 403 응답에 대비해 재시도 정책을 적용하는 것을 권장합니다.

ForbiddenException 의 세부 분류

data.reason 속성을 통해 ForbiddenException 의 구체적인 사유를 확인할 수 있습니다.

`data.reason`	설명
`FEATURE_NOT_INCLUDED`	요금제에 해당 기능이 포함되어 있지 않습니다.
`THROTTLE_EXCEEDED`	요금제가 제공하는 상한선을 초과하였습니다. 모두싸인에서는 사용량과 관계 없이 요금제 별로 특정 기능의 최대 상한선을 제한하고 있습니다. 예) 템플릿 수 최대 3개, 요청당 첨부파일 최대 10개 등
`SUBSCRIPTION_INACTIVE`	구독이 비활성화 되었습니다.

`FEATURE_NOT_INCLUDED` 인 경우

data.reason이 FEATURE_NOT_INCLUDED 인 경우, data.features 속성을 통해 어떤 기능의 부재로 인해 기능이 실패했는지 확인할수 있습니다.

`data.features`	설명
`DOCUMENT`	문서, 서명 요청
`TEMPLATE`	템플릿
`WEBHOOK`	웹훅
`ADVANCED_FIELDS`	고급 입력란
`PREFILLED_VALUE`	사전 입력 값
`TEMPLATE_MERGING`	템플릿 병합

`THROTTLE_EXCEEDED` 인 경우

data.reason 이 THROTTLE_EXCEEDED 인 경우, throttleName 속성을 통해 어떤 기능의 상한선을 초과했는지 확인 가능합니다.

`throttleName`	설명
`TEMPLATE_COUNT`	템플릿 보유 수량
`SIGNER_COUNT`	문서 / 템플릿 내 서명자 수
`ATTACHMENT_REQUEST_COUNT`	문서 / 템플릿 내 첨부파일 요청 수

404 Not Found

요청한 리소스를 찾을 수 없을 때 발생합니다.

에러 메시지	설명	해결 방법
`Not found`	요청한 리소스를 찾을 수 없음	• 요청 URL이 올바른지 확인 • 문서 ID나 리소스 ID가 존재하는지 확인
`Anchor text not found in PDF`	Anchor 텍스트가 문서 내에 존재하지 않음 (`AnchorTextNotFoundException`)	• `anchor.text` 값과 문서 내 텍스트가 정확히 일치하는지 확인 (대소문자, 공백, 특수문자 포함) • 스캔된 이미지 PDF인 경우 OCR 처리된 PDF 사용 • PDF 폰트 임베딩 이슈로 텍스트가 깨지지 않았는지 확인

422 처리 불가 에러

요청은 올바르지만 비즈니스 로직상 처리할 수 없을 때 발생하는 에러입니다.

문서 및 참여자 관련

에러 메시지	설명	해결 방법
`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개 이상 가질 수 없음	인증 타입을 중복되지 않게 설정

5xx 서버 에러

서버 내부에서 문제가 발생했을 때 나타나는 에러입니다.

코드	에러 메시지	설명	해결 방법
500	`Internal server error`	알 수 없는 서버 에러	잠시 후 재시도, 지속 시 기술지원팀 문의

문제 해결 체크리스트

문제가 지속될 때 다음 순서로 확인해보세요:

1. API 키 확인

올바른 키와 권한 설정이 되어있는지 확인

2. 요청 형식 검증

JSON 구조와 필수 파라미터가 올바른지 확인

3. 데이터 타입 확인

string, boolean, number 등 타입이 정확한지 확인

4. 용량 제한 확인

파일 개수, 메타데이터 개수 등 제한사항 확인

5. 문서 상태 확인

현재 문서가 요청 가능한 상태인지 확인

기술지원 문의 가이드

👍
API 호출 오류 발생 시, 아래 정보 모두 전달해 주시면 확인 후 안내드리겠습니다.
[필수 정보]

API 호출 시 사용 이메일

사용한 API (템플릿 서명요청 등)

오류 발생 시간 (년-월-일 시:분 형식)

에러 로그 (응답받은 전체 에러 메시지)

[선택 정보]

요청 본문 (민감정보 마스킹 후)

이 정보들을 제공해주시면 더 빠르고 정확한 기술지원을 받으실 수 있습니다.