documenso-common-errors

What this skill does

# 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 |
| 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](https://status.documenso.com) |

## Instructions

### Scenario 1: 401 Unauthorized

```typescript
// 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

```typescript
// 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)

```typescript
// 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)

```typescript
// 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)

```typescript
// 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

```text
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

```typescript
// 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
```

## Debugging Quick Commands

```bash
# 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

| 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 |

## Resources

- [Documenso API Reference](https://openapi.documenso.com/)
- [Status Page](https://status.documenso.com)
- [GitHub Issues](https://github.com/documenso/documenso/issues)
- Documenso Discord

## Next Steps

For comprehensive debugging, see `documenso-debug-bundle`.