API 에러 코드 참조 가이드

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

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

에러 코드 분류

클라이언트의 요청에 문제가 있을 때 발생하는 에러입니다.

400 Bad Request - 요청 오류

요청 형식이나 파라미터에 문제가 있을 때 발생합니다.

에러 메시지	설명	해결방법
Bad request	요청이 올바르지 않음	API 문서의 요청 형식을 확인하세요
Validation failed	요청이 올바르지 않음	필수 파라미터와 데이터 타입을 검토하세요
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가 존재하는지 확인

문제 해결 체크리스트

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

1. API 키 확인

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

2. 요청 형식 검증

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

3. 데이터 타입 확인

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

4. 용량 제한 확인

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

5. 문서 상태 확인

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

기술지원 문의 가이드

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

API 호출 시 사용 이메일

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

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

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

[선택 정보]

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

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