错误

错误使用 HTTP 状态码，响应体采用 RFC 9457 格式，并带有 Content-Type: application/problem+json：

{
  "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>`。请根据它（或其 slug）进行分支处理，而不是根据 `title` 或 `detail`
`title`	该类型的简短概述
`status`	HTTP 状态码
`detail`	针对本次错误的可读说明
`errors`	校验问题：`pointer`（指向请求体、查询参数或变量的 JSON Pointer）、`message`，以及可选的 `hint`
`requestId`	也包含在 `x-request-id` 响应头中。联系支持团队时请提供
`upgradeUrl`	出现在方案限制（`402`、`403 plan-upgrade-required`）中：添加银行卡或升级方案的地址

一个请求的所有校验问题会一次性全部报告，因此客户端可以把每个问题都显示在对应的字段旁边。

错误类型

状态码	Slug	触发时机
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`	该功能已在架构中定义，但尚未实现（例如短信验证码）
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})`);
  }
}