오류

오류는 HTTP 상태 코드와 Content-Type: application/problem+json인 RFC 9457 본문으로 반환됩니다.

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/recipients/0/email", "message": "Invalid email address" },
    { "pointer": "/recipients", "message": "Missing recipient for role 'company'." },
    { "pointer": "/recipients/1/role", "message": "Unknown role 'cfo'.", "hint": "Template roles: client, company" }
  ],
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

멤버	의미
`type`	안정적인 식별자: `https://bonafidesign.com/problems/<slug>`. `title`이나 `detail`이 아니라 이 값(또는 슬러그)으로 분기하세요
`title`	유형의 짧은 요약
`status`	HTTP 상태
`detail`	이번 발생에 대한 사람이 읽을 수 있는 설명
`errors`	검증 문제: `pointer`(요청 본문, 또는 쿼리나 변수 안을 가리키는 JSON Pointer), `message`, 선택적 `hint`
`requestId`	`x-request-id` 헤더에도 있습니다. 지원팀에 문의할 때 알려 주세요
`upgradeUrl`	플랜 제한(`402`, `403 plan-upgrade-required`)인 경우: 카드를 추가하거나 업그레이드할 수 있는 위치

요청의 모든 검증 문제가 한꺼번에 보고되므로, 클라이언트는 각 문제를 해당 필드 옆에 표시할 수 있습니다.

오류 유형

상태	슬러그	발생 시점
400	`bad-request`	본문이 유효한 JSON이 아닌 경우 등 잘못된 형식의 요청
401	`unauthorized`	자격 증명이 없거나, 형식이 잘못되었거나, 폐기되었거나, 만료됨
402	`payment-required`	Free 워크스페이스가 이번 기간에 포함된 봉투를 모두 완료함. 카드를 추가하거나 업그레이드하세요(테스트 모드는 영향 없음)
403	`forbidden`	인증되었지만 허용되지 않음: 권한 누락, 대시보드 전용 엔드포인트에서 API 키 사용, 크로스 사이트 요청
403	`plan-upgrade-required`	해당 기능이 워크스페이스의 플랜에 포함되지 않음
403	`verification-required`	서명자가 일회용 코드를 인증하기 전에 제출함
404	`not-found`	리소스가 조직에 없거나 경로가 존재하지 않음
409	`invalid-state`	작업이 현재 상태와 맞지 않음. 예: 완료된 봉투 무효화, 이미 서명한 수신자의 세션 발급
409	`not-your-turn`	이전 라우팅 그룹이 끝나기 전에 서명자가 제출함
409	`document-mismatch`	서명자에게 표시된 후 문서가 변경됨(`viewedDocumentHash`)
409	`already-signed`	해당 이메일 주소가 이미 이 상시 링크에 서명함
409	`in-use`	봉투나 서명 링크가 사용하는 템플릿을 삭제하려 함
409	`no-draft`	초안이 없는 템플릿을 게시하려 함
409	`idempotency-in-progress`	같은 `Idempotency-Key`의 요청이 아직 실행 중
409	`conflict`	기타 충돌
410	`gone`	이미 사용되었거나 만료된 서명 세션
413	`payload-too-large`	한도를 넘는 업로드(템플릿 파일은 25 MB)
415	`unsupported-media-type`	지원되지 않는 유형의 업로드
422	`validation-error`	본문, 쿼리 또는 변수가 유효하지 않음. `errors` 참조
422	`idempotency-key-reused`	같은 `Idempotency-Key`가 다른 요청에 사용됨
422	`conversion-failed`	Word 문서를 변환할 수 없음
429	`rate-limited`	요청이 너무 많음. `Retry-After`가 있으면 그 초만큼 기다리세요
500	`internal`	예기치 않은 오류. 같은 `Idempotency-Key`로 안전하게 재시도할 수 있습니다
501	`not-implemented`	스키마에는 있지만 아직 제공되지 않는 기능(예: SMS 코드)
503	`converter-unavailable`, `billing-unavailable`	의존 서비스를 일시적으로 사용할 수 없음. 나중에 다시 시도하세요

오류 처리

const res = await fetch('https://api.bonafidesign.com/v1/envelopes', { method: 'POST', headers, body });
if (!res.ok) {
  const problem = await res.json(); // application/problem+json
  const slug = problem.type.split('/').pop();
  if (slug === 'validation-error') {
    for (const e of problem.errors) form.setError(e.pointer, e.message);
  } else if (slug === 'payment-required') {
    showUpgrade(problem.upgradeUrl);
  } else {
    throw new Error(`${problem.title} (${problem.requestId})`);
  }
}