用途:这是一个 Documenso API 错误的快速排查参考,帮助定位集成失败原因并给出修复或升级处理建议。
主要能力:按 HTTP 状态码分类说明错误原因与解决方案,包括 401(API 密钥无效、过期或缺失,需在控制台重新生成并确认 Authorization: Bearer <key> 头)、403(个人密钥访问团队资源,需使用团队范围的 API Token)、404(文档或模板 ID 错误或资源已删除,可用 GET /api/v1/documents 核对)、400(请求体无效或缺少必填字段)、413(PDF 超出上传限制,可压缩 PDF,云计划上限因套餐而异)、429(超出速率限制,需实现退避)、500/502/503(服务端问题,可用指数退避重试并查看状态页)。
使用方式:文档只能在 DRAFT 状态修改,已发送文档需先取消再修改重发,取消会通知所有收件人。字段坐标 pageX、pageY 为百分比(0-100)而非像素。SDK 角色与字段类型需使用大写枚举,如 SIGNER、VIEWER、APPROVER、CC,以及 SIGNATURE、TEXT、DATE、NAME、EMAIL、INITIALS、NUMBER、CHECKBOX、DROPDOWN、RADIO、FREE_SIGNATURE。Webhook 需使用 HTTPS、在团队设置中启用并选择正确事件、端点须在 10 秒内返回 200,并校验 X-Documenso-Secret 头。
调试命令:可用 curl 测试密钥、检查自托管实例健康状态、列出文档验证访问权限。
限制:具体上传大小上限、速率限制数值等因套餐而异,资料未给出确切数值;部分场景需结合 documenso-install-auth、documenso-rate-limits、documenso-debug-bundle 等文档进一步排查。