From documenso-pack
Diagnoses and resolves common Documenso API errors like 401, 403, 429 with causes, solutions, checklists, and TypeScript fetch/SDK examples.
How this skill is triggered — by the user, by Claude, or both
Slash command
/documenso-pack:documenso-common-errorsThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Quick-reference troubleshooting guide for Documenso API errors. Covers authentication, document lifecycle, field validation, file upload, webhook, and SDK-specific issues with concrete solutions.
Quick-reference troubleshooting guide for Documenso API errors. Covers authentication, document lifecycle, field validation, file upload, webhook, and SDK-specific issues with concrete solutions.
documenso-install-auth)| Status | Error | Cause | Solution |
|---|---|---|---|
| 401 | Unauthorized | Invalid, expired, or missing API key | Regenerate key in dashboard; verify Authorization: Bearer <key> header |
| 403 | Forbidden | Personal key accessing team resources | Use a team-scoped API token |
| 404 | Not Found | Wrong document/template ID or deleted resource | Verify ID with GET /api/v1/documents |
| 400 | Bad Request | Invalid payload or missing required fields | Check request body against API spec |
| 413 | Payload Too Large | PDF exceeds upload limit | Compress PDF; cloud plan limit varies by tier |
| 429 | Too Many Requests | Rate limit exceeded | Implement backoff; see documenso-rate-limits |
| 500/502/503 | Server Error | Documenso infrastructure issue | Retry with exponential backoff; check status.documenso.com |
// 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_ (personal) or is team-scoped// 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
});
// 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
// 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
});
// 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`);
}
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
// Error: argument type mismatch with SDK
// The SDK uses specific enum strings, not arbitrary values
// WRONG
await client.documentsRecipients.createV0(docId, {
email: "[email protected]",
name: "Jane",
role: "signer", // Lowercase fails
});
// CORRECT: use uppercase enum values
await client.documentsRecipients.createV0(docId, {
email: "[email protected]",
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
# 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'
| Issue | Cause | Solution |
|---|---|---|
ERR_INVALID_URL | Bad serverURL in SDK config | Include protocol and path: https://host/api/v2 |
ECONNREFUSED | Self-hosted instance down | Check Docker container status |
Module not found | SDK not installed | Run npm install @documenso/sdk-typescript |
| Stale document data | Caching old state | Re-fetch document after status changes |
For comprehensive debugging, see documenso-debug-bundle.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin documenso-packApply production-ready Documenso SDK patterns for TypeScript and Python, including singleton clients, typed services, error handling, and testing.
Automates Documenso document workflows via Rube MCP and Composio's Documenso toolkit. Always discover tool schemas before execution.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.