Diagnose and resolve common Documenso API errors and issues.
Use when encountering Documenso errors, debugging integration issues,
or troubleshooting failed operations.
Trigger with phrases like "documenso error", "documenso 401",
"documenso failed", "fix documenso", "documenso not working".
Diagnose and resolve common Documenso API errors and issues.
Use when encountering Documenso errors, debugging integration issues,
or troubleshooting failed operations.
Trigger with phrases like "documenso error", "documenso 401",
"documenso failed", "fix documenso", "documenso not working".
allowed-tools
Read, Write, Edit, Grep
version
1.0.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
compatible-with
claude-code, codex, openclaw
tags
["saas","documenso","api","debugging"]
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
Status
Error
Cause
Solution
401
Unauthorized
Invalid, expired, or missing API key
Regenerate key in dashboard; verify Authorization: Bearer <key> header
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 Tokensconst client = newDocumenso({
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 firstconst doc = await client.documents.getV0(documentId);
if (doc.status !== "DRAFT") {
thrownewError(`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 coordinatesawait client.documentsFields.createV0(docId, {
recipientId, type: "SIGNATURE",
pageNumber: 1,
pageX: 200, // Invalid: > 100pageY: 600, // Invalid: > 100pageWidth: 150, pageHeight: 50,
});
// CORRECT: percentage coordinatesawait client.documentsFields.createV0(docId, {
recipientId, type: "SIGNATURE",
pageNumber: 1,
pageX: 10, // 10% from left edgepageY: 80, // 80% from top edgepageWidth: 30, // 30% of page widthpageHeight: 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 uploadimport { PDFDocument } from"pdf-lib";
const pdfDoc = awaitPDFDocument.load(readFileSync("large-contract.pdf"));
const compressed = await pdfDoc.save({ useObjectStreams: true });
// Upload compressed version// Solution 2: Check file size before uploadconstMAX_SIZE_MB = 10; // Varies by planconst fileSizeMB = readFileSync("contract.pdf").length / (1024 * 1024);
if (fileSizeMB > MAX_SIZE_MB) {
thrownewError(`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// WRONGawait client.documentsRecipients.createV0(docId, {
email: "signer@example.com",
name: "Jane",
role: "signer", // Lowercase fails
});
// CORRECT: use uppercase enum valuesawait 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'
