documenso-common-errors（文档常见错误）

Documenso Common Errors

Overview

Quick-reference troubleshooting guide for Documenso API errors. Covers authentication, document lifecycle, field validation, file upload, webhook, and SDK-specific issues with concrete solutions.

Prerequisites

• Working Documenso integration (see documenso-install-auth)
• Access to application logs
• API key available

HTTP Error Reference

Instructions

Scenario 1: 401 Unauthorized

// WRONG: missing or malformed header
const res = await fetch("https://app.documenso.com/api/v1/documents", {
  headers: { "Authorization": process.env.DOCUMENSO_API_KEY! }, // Missing "Bearer "
});

// CORRECT: include Bearer prefix
const res = await fetch("https://app.documenso.com/api/v1/documents", {
  headers: { "Authorization": `Bearer ${process.env.DOCUMENSO_API_KEY}` },
});

// SDK handles this automatically:
import { Documenso } from "@documenso/sdk-typescript";
const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });

Checklist:

• API key starts with api_ (personal) or is team-scoped
• No trailing whitespace or newline in env var
• Key hasn't been revoked in dashboard

Scenario 2: 403 — Personal Key on Team Resources

// Error: "Forbidden" when accessing team documents
// Personal API keys can only access YOUR documents
// Fix: generate a team API key from Team Settings > API Tokens
const client = new Documenso({
  apiKey: process.env.DOCUMENSO_TEAM_API_KEY!, // Team-scoped key
});

Scenario 3: Cannot Modify Sent Document (400)

// Error: trying to add fields to a PENDING document
// Documents can only be modified in DRAFT status

// Check status first
const doc = await client.documents.getV0(documentId);
if (doc.status !== "DRAFT") {
  throw new Error(`Cannot modify document in ${doc.status} status. Cancel first or create new.`);
}

// To re-edit: cancel the sent document, modify, then re-send
// Note: cancelling notifies all recipients

Scenario 4: Invalid Field Position (400)

// Error: field coordinates out of range
// pageX and pageY are PERCENTAGE-based (0-100), not pixel-based

// WRONG: pixel coordinates
await client.documentsFields.createV0(docId, {
  recipientId, type: "SIGNATURE",
  pageNumber: 1,
  pageX: 200,  // Invalid: > 100
  pageY: 600,  // Invalid: > 100
  pageWidth: 150, pageHeight: 50,
});

// CORRECT: percentage coordinates
await client.documentsFields.createV0(docId, {
  recipientId, type: "SIGNATURE",
  pageNumber: 1,
  pageX: 10,     // 10% from left edge
  pageY: 80,     // 80% from top edge
  pageWidth: 30, // 30% of page width
  pageHeight: 5, // 5% of page height
});

Scenario 5: File Upload Errors (413)

// Error: PDF too large for upload
// Cloud plans have per-document size limits

// Solution 1: Compress PDF before upload
import { PDFDocument } from "pdf-lib";
const pdfDoc = await PDFDocument.load(readFileSync("large-contract.pdf"));
const compressed = await pdfDoc.save({ useObjectStreams: true });
// Upload compressed version

// Solution 2: Check file size before upload
const MAX_SIZE_MB = 10; // Varies by plan
const fileSizeMB = readFileSync("contract.pdf").length / (1024 * 1024);
if (fileSizeMB > MAX_SIZE_MB) {
  throw new Error(`PDF is ${fileSizeMB.toFixed(1)}MB, max is ${MAX_SIZE_MB}MB`);
}

Scenario 6: Webhook Not Receiving Events

Checklist:
1. Webhook URL uses HTTPS (HTTP is rejected)
2. Webhook is enabled in Team Settings > Webhooks
3. Correct events are selected (document.completed, etc.)
4. Your endpoint returns 200 within 10 seconds
5. If using ngrok: tunnel is active and URL matches dashboard config
6. Check X-Documenso-Secret header matches your stored secret

Scenario 7: SDK Type Mismatches

// Error: argument type mismatch with SDK
// The SDK uses specific enum strings, not arbitrary values

// WRONG
await client.documentsRecipients.createV0(docId, {
  email: "signer@example.com",
  name: "Jane",
  role: "signer", // Lowercase fails
});

// CORRECT: use uppercase enum values
await client.documentsRecipients.createV0(docId, {
  email: "signer@example.com",
  name: "Jane",
  role: "SIGNER", // Must be uppercase: SIGNER, VIEWER, APPROVER, CC
});

// Field types are also uppercase: SIGNATURE, TEXT, DATE, NAME, EMAIL,
// INITIALS, NUMBER, CHECKBOX, DROPDOWN, RADIO, FREE_SIGNATURE

Debugging Quick Commands

# Test API key
curl -s -w "\n%{http_code}" \
  -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  https://app.documenso.com/api/v1/documents?page=1&perPage=1

# Check self-hosted instance health
curl -s https://your-instance.com/api/health

# List documents to verify access
curl -s -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  "https://app.documenso.com/api/v1/documents?page=1&perPage=5" | jq '.documents[].title'

Error Handling

Resources

• Documenso API Reference
• Status Page
• GitHub Issues
• Documenso Discord

Next Steps

For comprehensive debugging, see documenso-debug-bundle.