오류 코드
오류가 나면 HTTP 상태와 error.code를 같이 보세요. 상태는 코드가 오류 종류별로 정해요.
POST /api/contracts:send_document 오류 코드
출처: SEND_DOCUMENT_ERRORS (app/src/api/send-document-errors.ts). 응답 본문은 { "error": { "type", "code", "message", "request_id", "retryable", "field"? } } 모양이에요.
| HTTP | 코드 | 모드 | 언제 나요 |
|---|---|---|---|
| 401 | tenant_unresolved | all | Bearer 토큰(sk_/oat_)이 없거나 무효 |
| 403 | insufficient_scope | all | 토큰에 contract:send 권한 없음 |
| 422 | idempotency_key_required | all | Idempotency-Key 헤더 없음 |
| 400 | invalid_json | all | 본문이 JSON 이 아님 |
| 400 | invalid_body | all | 본문이 JSON 객체가 아님 |
| 422 | body_too_large | all | 본문 JSON 이 7,300,000자 초과 |
| 422 | field_required | all | 필수 문자열 없음(title · sign 의 body_markdown · deliver_pdf/sign_pdf 의 pdf_base64) — field 로 구분 |
| 422 | title_invalid | all | title 공백이거나 200자 초과 |
| 422 | client_ref_invalid | all | client_ref 가 영문·숫자·._:- 128자 이하가 아님 |
| 422 | expires_in_days_invalid | all | expires_in_days 가 1~30 정수가 아님 |
| 422 | too_many_items | all | recipients 500명 초과 |
| 422 | recipient_invalid | all | 수신자 이름 없음/100자 초과 또는 휴대폰·이메일 둘 다 없음 |
| 422 | recipient_phone_invalid | all | 수신자 휴대폰 형식 오류 |
| 422 | recipient_email_invalid | all | 수신자 이메일 형식 오류 |
| 422 | recipients_required | all | recipients 0명 |
| 422 | mode_invalid | all | mode 가 sign·deliver_pdf·sign_pdf 가 아님 |
| 422 | document_kind_invalid | all | mode 와 맞지 않는 document_kind |
| 422 | subject_required | sign, deliver_pdf, sign_pdf | subject(이름 2자 이상·휴대폰) 없음/형식 오류 — sign_pdf 는 employment_contract 이거나 subject 를 보낸 경우 |
| 422 | single_recipient_required | sign, deliver_pdf, sign_pdf | 수신자 2명 이상(sign·deliver_pdf 항상 · sign_pdf 는 employment_contract) |
| 422 | recipients_roles_mismatch | sign, sign_pdf | 수신 역할 수와 recipients 수가 다름 / recipients[].role 이 역할과 1:1 이 아님 |
| 422 | employer_seal_image_invalid | sign, sign_pdf | employer_seal_image 가 PNG/JPEG data URL 이 아님(매직바이트) |
| 422 | employer_seal_image_too_large | sign, sign_pdf | employer_seal_image 디코드 300KB 초과 |
| 422 | employer_seal_image_not_applicable | deliver_pdf, sign_pdf | deliver_pdf 에 보냄 / sign_pdf 인데 발신 역할(side:sender) 없음 |
| 422 | preview_document_invalid | all | preview_document 가 sign_pdf 의 "pdf" 가 아님 |
| 422 | preview_requires_dry_run | sign_pdf | preview_document:"pdf" 와 dry_run:false 를 함께 보냄 |
| 422 | roles_invalid | sign, sign_pdf | roles 개수·role id 형식·라벨·중복·발신 역할 수 오류(sign: is_sender 정확히 1 · sign_pdf: sender ≤1·recipient ≥1) |
| 422 | field_too_long | sign | body_markdown 200,000자 초과 |
| 422 | unresolved_placeholder | sign | 본문에 {{sig|seal|date:role}} 외의 {{…}} 가 남음 |
| 422 | role_undeclared | sign | 본문 토큰의 역할이 roles 에 없음 |
| 422 | date_token_duplicate | sign | 같은 역할의 {{date:role}} 가 2번 이상 |
| 422 | role_signature_missing | sign | 역할의 {{sig:role}}·{{seal:role}} 가 본문에 없음 |
| 422 | recipient_contract_mismatch | sign, sign_pdf | subject 와 수신자 이름·휴대폰이 다름 / sign 은 본문 수신 역할 서명란에 subject 이름이 없음 |
| 422 | channel_invalid | deliver_pdf | channel 이 'sms'·'auto' 가 아님 |
| 422 | recipient_document_mismatch | deliver_pdf | subject 와 수령인 이름·휴대폰이 다름 |
| 422 | certificate_no_required | deliver_pdf | certificate_no 없음 |
| 422 | certificate_no_invalid | deliver_pdf | certificate_no 형식·길이 오류 |
| 422 | pdf_too_large | deliver_pdf, sign_pdf | PDF 5MB 초과(base64 길이 또는 디코드 바이트) |
| 422 | pdf_invalid | deliver_pdf, sign_pdf | base64 아님 / 디코드 불가 / %PDF- 머리글 없음 / 손상·암호화로 읽기 실패 |
| 422 | pdf_no_pages | deliver_pdf, sign_pdf | PDF 쪽 수 0 |
| 422 | document_source_ambiguous | sign_pdf | pdf_base64 와 document_ref 를 둘 다 보냄 |
| 422 | document_ref_invalid | sign_pdf | document_ref 가 "sha256:<64 hex>" 가 아님 |
| 404 | document_not_found | sign_pdf | document_ref 의 PDF 가 이 조직에 없음(다른 조직 포함) |
| 409 | document_ref_mismatch | sign_pdf | 저장된 PDF 해시가 document_ref 와 다름 |
| 422 | pdf_rotated | sign_pdf | 회전(/Rotate)된 쪽이 있는 PDF |
| 422 | recipient_role_required | sign_pdf | recipients[].role 을 일부만 넣음 |
| 422 | fields_required | sign_pdf | fields 가 비었거나 배열이 아님 |
| 422 | too_many_fields | sign_pdf | 칸 60개 초과 |
| 422 | field_invalid | sign_pdf | 칸이 객체가 아님 / x·y·w·h 숫자 아님 / dataType·fontSize(4~24)·align 오류 |
| 422 | field_type_invalid | sign_pdf | type 이 signature·seal·date·text·checkbox 가 아님 |
| 422 | role_unknown | sign_pdf | 칸의 role 이 roles 에 없음 |
| 422 | field_side_mismatch | sign_pdf | 칸의 side 가 역할의 side 와 다름 |
| 422 | field_out_of_page | sign_pdf | page 가 1~쪽수 밖 / x,y<0 또는 x+w>1 또는 y+h>1(0~1 왼쪽 위 비율) |
| 422 | field_too_small | sign_pdf | 너비 0.01 · 높이 0.008 미만 |
| 422 | field_type_not_allowed | sign_pdf | 발신 역할에 checkbox 칸 |
| 422 | field_key_invalid | sign_pdf | key 가 영문 소문자로 시작하는 소문자·숫자·_ 40자 이하가 아님 |
| 422 | field_key_duplicate | sign_pdf | 같은 key 2번 |
| 422 | field_value_not_allowed | sign_pdf | 발신 text 칸이 아닌 곳에 value |
| 422 | field_value_invalid | sign_pdf | value 가 문자열이 아니거나 500자 초과 |
| 422 | field_value_required | sign_pdf | 발신 text 칸에 value 없음(빈칸 발송 방지) |
| 422 | field_overlap | sign_pdf | 다른 역할의 칸끼리 겹침 |
| 422 | missing_signature_field | sign_pdf | 수신 역할에 signature·seal 칸이 없음 |
| 409 | storage_unavailable | sign_pdf | 문서 저장소(R2) 바인딩 없음 (실발송 단계) |
| 422 | confirmation_required | all | confirmation_token 없음·만료·위조·이미 사용 (실발송 단계) |
| 422 | confirmation_payload_mismatch | all | 미리보기 뒤 요청 내용(sign_pdf 는 칸·역할·문서 layout_hash 포함)이 바뀜 (실발송 단계) |
| 409 | idempotency_conflict | all | 같은 client_ref 또는 Idempotency-Key 가 다른 요청 내용에 이미 쓰임 (실발송 단계) |
| 409 | idempotency_incomplete | all | 같은 client_ref 의 이전/동시 요청이 아직 끝나지 않음(retryable) (실발송 단계) |
| 402 | org_unverified | all | 조직에 이메일·휴대폰 인증을 마친 사용자가 없음 (실발송 단계) |
| 409 | sender_unresolved | all | 조직 발신자(대표 사용자)를 찾을 수 없음 (실발송 단계) |
| 409 | sender_phone_required | deliver_pdf | 조직 대표 사용자의 휴대폰 미등록 (실발송 단계) |
| 422 | invalid_input | sign_pdf | 계약 생성 시 받는 사람/역할 수 불일치(도메인) (실발송 단계) |
| 422 | sender_signature_unavailable | sign_pdf | 발신 서명·도장 칸 이미지를 만들지 못함(employer_seal_image 없고 기본 서명 렌더 실패) (실발송 단계) |
| 422 | merge_render_failed | sign_pdf | 발신 text 값(한글)을 PDF 에 굽지 못함(문서 렌더 일시 오류) (실발송 단계) |
| 422 | no_deliverable_recipient | all | 전달 가능한 수신 채널(휴대폰·이메일·설정) 없음 (실발송 단계) |
| 402 | payment_method_required | all | 무료·충전 발송권 모두 소진 (실발송 단계) |
| 409 | billing_failed | all | 정산 단계 예기치 않은 오류(원상복구됨 · retryable) (실발송 단계) |
| 409 | invalid_state | all | 계약 상태가 발송할 수 없는 상태(도메인) (실발송 단계) |
| 409 | illegal_transition | all | 허용되지 않는 상태 전이(도메인) (실발송 단계) |
| 404 | not_found | all | 대상 리소스 없음(도메인 not_found — 다른 조직 은폐 포함) (실발송 단계) |
요청별 오류 응답 (OpenAPI)
| 상태 | 어디서 나요 |
|---|---|
302 | GET /oauth/authorize — Login/consent redirect |
400 | POST /api/contracts:send_document — 오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:
- `invalid_json` — 본문이 JSON 이 아님
- `invalid_body` — 본문이 JSON 객체가 아님 |
401 | POST /mcp — OAuth protected resource challengePOST /api/contracts:send_document — 오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:
- `tenant_unresolved` — Bearer 토큰(sk_/oat_)이 없거나 무효 |
402 | POST /api/contracts/{id}:send — Payment requiredPOST /api/contracts:send_document — 오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:
- `org_unverified` (확정 단계) — 조직에 이메일·휴대폰 인증을 마친 사용자가 없음
- `payment_method_required` (확정 단계) — 무료·충전 발송권 모두 소진 |
403 | POST /api/contracts:send_document — 오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:
- `insufficient_scope` — 토큰에 contract:send 권한 없음 |
404 | GET /api/contracts/{id} — 성공 응답POST /api/contracts:send_document — 오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:
- `document_not_found` [sign_pdf] — document_ref 의 PDF 가 이 조직에 없음(다른 조직 포함)
- `not_found` (확정 단계) — 대상 리소스 없음(도메인 not_found — 다른 조직 은폐 포함) |
409 | POST /api/contracts:send_document — 오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:
- `document_ref_mismatch` [sign_pdf] — 저장된 PDF 해시가 document_ref 와 다름
- `storage_unavailable` [sign_pdf] (확정 단계) — 문서 저장소(R2) 바인딩 없음
- `idempotency_conflict` (확정 단계) — 같은 client_ref 또는 Idempotency-Key 가 다른 요청 내용에 이미 쓰임
- `idempotency_incomplete` (확정 단계) — 같은 client_ref 의 이전/동시 요청이 아직 끝나지 않음(retryable)
- `sender_unresolved` (확정 단계) — 조직 발신자(대표 사용자)를 찾을 수 없음
- `sender_phone_required` [deliver_pdf] (확정 단계) — 조직 대표 사용자의 휴대폰 미등록
- `billing_failed` (확정 단계) — 정산 단계 예기치 않은 오류(원상복구됨 · retryable)
- `invalid_state` (확정 단계) — 계약 상태가 발송할 수 없는 상태(도메인)
- `illegal_transition` (확정 단계) — 허용되지 않는 상태 전이(도메인) |
422 | POST /api/contracts:send_document — 오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:
- `idempotency_key_required` — Idempotency-Key 헤더 없음
- `body_too_large` — 본문 JSON 이 7,300,000자 초과
- `field_required` — 필수 문자열 없음(title · sign 의 body_markdown · deliver_pdf/sign_pdf 의 pdf_base64) — field 로 구분
- `title_invalid` — title 공백이거나 200자 초과
- `client_ref_invalid` — client_ref 가 영문·숫자·._:- 128자 이하가 아님
- `expires_in_days_invalid` — expires_in_days 가 1~30 정수가 아님
- `too_many_items` — recipients 500명 초과
- `recipient_invalid` — 수신자 이름 없음/100자 초과 또는 휴대폰·이메일 둘 다 없음
- `recipient_phone_invalid` — 수신자 휴대폰 형식 오류
- `recipient_email_invalid` — 수신자 이메일 형식 오류
- `recipients_required` — recipients 0명
- `mode_invalid` — mode 가 sign·deliver_pdf·sign_pdf 가 아님
- `document_kind_invalid` — mode 와 맞지 않는 document_kind
- `subject_required` [sign·deliver_pdf·sign_pdf] — subject(이름 2자 이상·휴대폰) 없음/형식 오류 — sign_pdf 는 employment_contract 이거나 subject 를 보낸 경우
- `single_recipient_required` [sign·deliver_pdf·sign_pdf] — 수신자 2명 이상(sign·deliver_pdf 항상 · sign_pdf 는 employment_contract)
- `recipients_roles_mismatch` [sign·sign_pdf] — 수신 역할 수와 recipients 수가 다름 / recipients[].role 이 역할과 1:1 이 아님
- `employer_seal_image_invalid` [sign·sign_pdf] — employer_seal_image 가 PNG/JPEG data URL 이 아님(매직바이트)
- `employer_seal_image_too_large` [sign·sign_pdf] — employer_seal_image 디코드 300KB 초과
- `employer_seal_image_not_applicable` [deliver_pdf·sign_pdf] — deliver_pdf 에 보냄 / sign_pdf 인데 발신 역할(side:sender) 없음
- `preview_document_invalid` — preview_document 가 sign_pdf 의 "pdf" 가 아님
- `preview_requires_dry_run` [sign_pdf] — preview_document:"pdf" 와 dry_run:false 를 함께 보냄
- `roles_invalid` [sign·sign_pdf] — roles 개수·role id 형식·라벨·중복·발신 역할 수 오류(sign: is_sender 정확히 1 · sign_pdf: sender ≤1·recipient ≥1)
- `field_too_long` [sign] — body_markdown 200,000자 초과
- `unresolved_placeholder` [sign] — 본문에 {{sig|seal|date:role}} 외의 {{…}} 가 남음
- `role_undeclared` [sign] — 본문 토큰의 역할이 roles 에 없음
- `date_token_duplicate` [sign] — 같은 역할의 {{date:role}} 가 2번 이상
- `role_signature_missing` [sign] — 역할의 {{sig:role}}·{{seal:role}} 가 본문에 없음
- `recipient_contract_mismatch` [sign·sign_pdf] — subject 와 수신자 이름·휴대폰이 다름 / sign 은 본문 수신 역할 서명란에 subject 이름이 없음
- `channel_invalid` [deliver_pdf] — channel 이 'sms'·'auto' 가 아님
- `recipient_document_mismatch` [deliver_pdf] — subject 와 수령인 이름·휴대폰이 다름
- `certificate_no_required` [deliver_pdf] — certificate_no 없음
- `certificate_no_invalid` [deliver_pdf] — certificate_no 형식·길이 오류
- `pdf_too_large` [deliver_pdf·sign_pdf] — PDF 5MB 초과(base64 길이 또는 디코드 바이트)
- `pdf_invalid` [deliver_pdf·sign_pdf] — base64 아님 / 디코드 불가 / %PDF- 머리글 없음 / 손상·암호화로 읽기 실패
- `pdf_no_pages` [deliver_pdf·sign_pdf] — PDF 쪽 수 0
- `document_source_ambiguous` [sign_pdf] — pdf_base64 와 document_ref 를 둘 다 보냄
- `document_ref_invalid` [sign_pdf] — document_ref 가 "sha256:<64 hex>" 가 아님
- `pdf_rotated` [sign_pdf] — 회전(/Rotate)된 쪽이 있는 PDF
- `recipient_role_required` [sign_pdf] — recipients[].role 을 일부만 넣음
- `fields_required` [sign_pdf] — fields 가 비었거나 배열이 아님
- `too_many_fields` [sign_pdf] — 칸 60개 초과
- `field_invalid` [sign_pdf] — 칸이 객체가 아님 / x·y·w·h 숫자 아님 / dataType·fontSize(4~24)·align 오류
- `field_type_invalid` [sign_pdf] — type 이 signature·seal·date·text·checkbox 가 아님
- `role_unknown` [sign_pdf] — 칸의 role 이 roles 에 없음
- `field_side_mismatch` [sign_pdf] — 칸의 side 가 역할의 side 와 다름
- `field_out_of_page` [sign_pdf] — page 가 1~쪽수 밖 / x,y<0 또는 x+w>1 또는 y+h>1(0~1 왼쪽 위 비율)
- `field_too_small` [sign_pdf] — 너비 0.01 · 높이 0.008 미만
- `field_type_not_allowed` [sign_pdf] — 발신 역할에 checkbox 칸
- `field_key_invalid` [sign_pdf] — key 가 영문 소문자로 시작하는 소문자·숫자·_ 40자 이하가 아님
- `field_key_duplicate` [sign_pdf] — 같은 key 2번
- `field_value_not_allowed` [sign_pdf] — 발신 text 칸이 아닌 곳에 value
- `field_value_invalid` [sign_pdf] — value 가 문자열이 아니거나 500자 초과
- `field_value_required` [sign_pdf] — 발신 text 칸에 value 없음(빈칸 발송 방지)
- `field_overlap` [sign_pdf] — 다른 역할의 칸끼리 겹침
- `missing_signature_field` [sign_pdf] — 수신 역할에 signature·seal 칸이 없음
- `confirmation_required` (확정 단계) — confirmation_token 없음·만료·위조·이미 사용
- `confirmation_payload_mismatch` (확정 단계) — 미리보기 뒤 요청 내용(sign_pdf 는 칸·역할·문서 layout_hash 포함)이 바뀜
- `invalid_input` [sign_pdf] (확정 단계) — 계약 생성 시 받는 사람/역할 수 불일치(도메인)
- `sender_signature_unavailable` [sign_pdf] (확정 단계) — 발신 서명·도장 칸 이미지를 만들지 못함(employer_seal_image 없고 기본 서명 렌더 실패)
- `merge_render_failed` [sign_pdf] (확정 단계) — 발신 text 값(한글)을 PDF 에 굽지 못함(문서 렌더 일시 오류)
- `no_deliverable_recipient` (확정 단계) — 전달 가능한 수신 채널(휴대폰·이메일·설정) 없음 |