싸인딜 개발자

오류 코드

오류가 나면 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코드모드언제 나요
401tenant_unresolvedallBearer 토큰(sk_/oat_)이 없거나 무효
403insufficient_scopeall토큰에 contract:send 권한 없음
422idempotency_key_requiredallIdempotency-Key 헤더 없음
400invalid_jsonall본문이 JSON 이 아님
400invalid_bodyall본문이 JSON 객체가 아님
422body_too_largeall본문 JSON 이 7,300,000자 초과
422field_requiredall필수 문자열 없음(title · sign 의 body_markdown · deliver_pdf/sign_pdf 의 pdf_base64) — field 로 구분
422title_invalidalltitle 공백이거나 200자 초과
422client_ref_invalidallclient_ref 가 영문·숫자·._:- 128자 이하가 아님
422expires_in_days_invalidallexpires_in_days 가 1~30 정수가 아님
422too_many_itemsallrecipients 500명 초과
422recipient_invalidall수신자 이름 없음/100자 초과 또는 휴대폰·이메일 둘 다 없음
422recipient_phone_invalidall수신자 휴대폰 형식 오류
422recipient_email_invalidall수신자 이메일 형식 오류
422recipients_requiredallrecipients 0명
422mode_invalidallmode 가 sign·deliver_pdf·sign_pdf 가 아님
422document_kind_invalidallmode 와 맞지 않는 document_kind
422subject_requiredsign, deliver_pdf, sign_pdfsubject(이름 2자 이상·휴대폰) 없음/형식 오류 — sign_pdf 는 employment_contract 이거나 subject 를 보낸 경우
422single_recipient_requiredsign, deliver_pdf, sign_pdf수신자 2명 이상(sign·deliver_pdf 항상 · sign_pdf 는 employment_contract)
422recipients_roles_mismatchsign, sign_pdf수신 역할 수와 recipients 수가 다름 / recipients[].role 이 역할과 1:1 이 아님
422employer_seal_image_invalidsign, sign_pdfemployer_seal_image 가 PNG/JPEG data URL 이 아님(매직바이트)
422employer_seal_image_too_largesign, sign_pdfemployer_seal_image 디코드 300KB 초과
422employer_seal_image_not_applicabledeliver_pdf, sign_pdfdeliver_pdf 에 보냄 / sign_pdf 인데 발신 역할(side:sender) 없음
422preview_document_invalidallpreview_document 가 sign_pdf 의 "pdf" 가 아님
422preview_requires_dry_runsign_pdfpreview_document:"pdf" 와 dry_run:false 를 함께 보냄
422roles_invalidsign, sign_pdfroles 개수·role id 형식·라벨·중복·발신 역할 수 오류(sign: is_sender 정확히 1 · sign_pdf: sender ≤1·recipient ≥1)
422field_too_longsignbody_markdown 200,000자 초과
422unresolved_placeholdersign본문에 {{sig|seal|date:role}} 외의 {{…}} 가 남음
422role_undeclaredsign본문 토큰의 역할이 roles 에 없음
422date_token_duplicatesign같은 역할의 {{date:role}} 가 2번 이상
422role_signature_missingsign역할의 {{sig:role}}·{{seal:role}} 가 본문에 없음
422recipient_contract_mismatchsign, sign_pdfsubject 와 수신자 이름·휴대폰이 다름 / sign 은 본문 수신 역할 서명란에 subject 이름이 없음
422channel_invaliddeliver_pdfchannel 이 'sms'·'auto' 가 아님
422recipient_document_mismatchdeliver_pdfsubject 와 수령인 이름·휴대폰이 다름
422certificate_no_requireddeliver_pdfcertificate_no 없음
422certificate_no_invaliddeliver_pdfcertificate_no 형식·길이 오류
422pdf_too_largedeliver_pdf, sign_pdfPDF 5MB 초과(base64 길이 또는 디코드 바이트)
422pdf_invaliddeliver_pdf, sign_pdfbase64 아님 / 디코드 불가 / %PDF- 머리글 없음 / 손상·암호화로 읽기 실패
422pdf_no_pagesdeliver_pdf, sign_pdfPDF 쪽 수 0
422document_source_ambiguoussign_pdfpdf_base64 와 document_ref 를 둘 다 보냄
422document_ref_invalidsign_pdfdocument_ref 가 "sha256:<64 hex>" 가 아님
404document_not_foundsign_pdfdocument_ref 의 PDF 가 이 조직에 없음(다른 조직 포함)
409document_ref_mismatchsign_pdf저장된 PDF 해시가 document_ref 와 다름
422pdf_rotatedsign_pdf회전(/Rotate)된 쪽이 있는 PDF
422recipient_role_requiredsign_pdfrecipients[].role 을 일부만 넣음
422fields_requiredsign_pdffields 가 비었거나 배열이 아님
422too_many_fieldssign_pdf칸 60개 초과
422field_invalidsign_pdf칸이 객체가 아님 / x·y·w·h 숫자 아님 / dataType·fontSize(4~24)·align 오류
422field_type_invalidsign_pdftype 이 signature·seal·date·text·checkbox 가 아님
422role_unknownsign_pdf칸의 role 이 roles 에 없음
422field_side_mismatchsign_pdf칸의 side 가 역할의 side 와 다름
422field_out_of_pagesign_pdfpage 가 1~쪽수 밖 / x,y<0 또는 x+w>1 또는 y+h>1(0~1 왼쪽 위 비율)
422field_too_smallsign_pdf너비 0.01 · 높이 0.008 미만
422field_type_not_allowedsign_pdf발신 역할에 checkbox 칸
422field_key_invalidsign_pdfkey 가 영문 소문자로 시작하는 소문자·숫자·_ 40자 이하가 아님
422field_key_duplicatesign_pdf같은 key 2번
422field_value_not_allowedsign_pdf발신 text 칸이 아닌 곳에 value
422field_value_invalidsign_pdfvalue 가 문자열이 아니거나 500자 초과
422field_value_requiredsign_pdf발신 text 칸에 value 없음(빈칸 발송 방지)
422field_overlapsign_pdf다른 역할의 칸끼리 겹침
422missing_signature_fieldsign_pdf수신 역할에 signature·seal 칸이 없음
409storage_unavailablesign_pdf문서 저장소(R2) 바인딩 없음 (실발송 단계)
422confirmation_requiredallconfirmation_token 없음·만료·위조·이미 사용 (실발송 단계)
422confirmation_payload_mismatchall미리보기 뒤 요청 내용(sign_pdf 는 칸·역할·문서 layout_hash 포함)이 바뀜 (실발송 단계)
409idempotency_conflictall같은 client_ref 또는 Idempotency-Key 가 다른 요청 내용에 이미 쓰임 (실발송 단계)
409idempotency_incompleteall같은 client_ref 의 이전/동시 요청이 아직 끝나지 않음(retryable) (실발송 단계)
402org_unverifiedall조직에 이메일·휴대폰 인증을 마친 사용자가 없음 (실발송 단계)
409sender_unresolvedall조직 발신자(대표 사용자)를 찾을 수 없음 (실발송 단계)
409sender_phone_requireddeliver_pdf조직 대표 사용자의 휴대폰 미등록 (실발송 단계)
422invalid_inputsign_pdf계약 생성 시 받는 사람/역할 수 불일치(도메인) (실발송 단계)
422sender_signature_unavailablesign_pdf발신 서명·도장 칸 이미지를 만들지 못함(employer_seal_image 없고 기본 서명 렌더 실패) (실발송 단계)
422merge_render_failedsign_pdf발신 text 값(한글)을 PDF 에 굽지 못함(문서 렌더 일시 오류) (실발송 단계)
422no_deliverable_recipientall전달 가능한 수신 채널(휴대폰·이메일·설정) 없음 (실발송 단계)
402payment_method_requiredall무료·충전 발송권 모두 소진 (실발송 단계)
409billing_failedall정산 단계 예기치 않은 오류(원상복구됨 · retryable) (실발송 단계)
409invalid_stateall계약 상태가 발송할 수 없는 상태(도메인) (실발송 단계)
409illegal_transitionall허용되지 않는 상태 전이(도메인) (실발송 단계)
404not_foundall대상 리소스 없음(도메인 not_found — 다른 조직 은폐 포함) (실발송 단계)

요청별 오류 응답 (OpenAPI)

상태어디서 나요
302GET /oauth/authorize — Login/consent redirect
400POST /api/contracts:send_document — 오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code: - `invalid_json` — 본문이 JSON 이 아님 - `invalid_body` — 본문이 JSON 객체가 아님
401POST /mcp — OAuth protected resource challenge
POST /api/contracts:send_document — 오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code: - `tenant_unresolved` — Bearer 토큰(sk_/oat_)이 없거나 무효
402POST /api/contracts/{id}:send — Payment required
POST /api/contracts:send_document — 오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code: - `org_unverified` (확정 단계) — 조직에 이메일·휴대폰 인증을 마친 사용자가 없음 - `payment_method_required` (확정 단계) — 무료·충전 발송권 모두 소진
403PUT /api/templates/{id}/fields — template_readonly
PUT /api/templates/{id}/roles — template_readonly
POST /api/contracts:send_document — 오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code: - `insufficient_scope` — 토큰에 contract:send 권한 없음
404GET /api/contracts/{id} — 성공 응답
POST /api/templates — document_not_found
GET /api/templates/{id} — 성공 응답
PUT /api/templates/{id}/fields — 성공 응답
PUT /api/templates/{id}/roles — 성공 응답
GET /api/templates/{id}/versions — 성공 응답
GET /api/contracts/{id}/pdf — 성공 응답
GET /api/contracts/{id}/deliveries/{trackingId} — 계약 없음 또는 tracking_id 불일치
DELETE /api/integrations/webhooks/{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 — 다른 조직 은폐 포함)
409POST /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` (확정 단계) — 허용되지 않는 상태 전이(도메인)
422POST /api/templates — 엔진·입력 검증 오류
PUT /api/templates/{id}/fields — 엔진 검증 오류
PUT /api/templates/{id}/roles — roles_invalid · roles_shape_mismatch
POST /api/documents — pdf_too_large · pdf_invalid · pdf_no_pages · pdf_too_many_pages · pdf_rotated · field_required
POST /api/integrations/webhooks — webhook_config_invalid
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` (확정 단계) — 전달 가능한 수신 채널(휴대폰·이메일·설정) 없음