From 3c9c490505fbb04ba7d1b78e4c9b3fec8d24f2fb Mon Sep 17 00:00:00 2001 From: ephraimduncan Date: Thu, 30 Jul 2026 21:37:51 +0000 Subject: [PATCH] docs(getting-started): fix distribute route, pagination and retry advice - POST /envelope/{id}/distribute does not exist; use POST /envelope/distribute with body - list responses are flat (data, count, currentPage, perPage, totalPages), not nested pagination - replace fixed 60s sleep advice with Retry-After header handling --- .../getting-started/first-api-call.mdx | 67 ++++++++++--------- 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/apps/docs/content/docs/developers/getting-started/first-api-call.mdx b/apps/docs/content/docs/developers/getting-started/first-api-call.mdx index e87b85438..d1cc4f46a 100644 --- a/apps/docs/content/docs/developers/getting-started/first-api-call.mdx +++ b/apps/docs/content/docs/developers/getting-started/first-api-call.mdx @@ -78,12 +78,10 @@ A successful response returns a list of your documents (envelopes): "createdAt": "2025-01-15T10:30:00.000Z" } ], - "pagination": { - "page": 1, - "perPage": 10, - "totalPages": 1, - "totalItems": 1 - } + "count": 1, + "currentPage": 1, + "perPage": 10, + "totalPages": 1 } ```` @@ -228,9 +226,12 @@ After creating a document, it's in `DRAFT` status. To send it to recipients, use ```bash -curl -X POST "https://app.documenso.com/api/v2/envelope/envelope_abc123/distribute" \ +curl -X POST "https://app.documenso.com/api/v2/envelope/distribute" \ -H "Authorization: YOUR_API_TOKEN" \ - -H "Content-Type: application/json" + -H "Content-Type: application/json" \ + -d '{ + "envelopeId": "envelope_abc123" + }' ```` @@ -238,16 +239,14 @@ curl -X POST "https://app.documenso.com/api/v2/envelope/envelope_abc123/distribu ```javascript const envelopeId = 'envelope_abc123'; -const response = await fetch( - `https://app.documenso.com/api/v2/envelope/${envelopeId}/distribute`, - { - method: 'POST', - headers: { - Authorization: 'YOUR_API_TOKEN', - 'Content-Type': 'application/json', - }, +const response = await fetch('https://app.documenso.com/api/v2/envelope/distribute', { + method: 'POST', + headers: { + Authorization: 'YOUR_API_TOKEN', + 'Content-Type': 'application/json', }, -); + body: JSON.stringify({ envelopeId }), +}); const data = await response.json(); console.log('Document sent:', data); @@ -337,16 +336,14 @@ async function createAndSendDocument(pdfPath, recipientEmail, recipientName) { console.log('Created envelope:', envelope.id); // Step 2: Send the document for signing - const distributeResponse = await fetch( - `${BASE_URL}/envelope/${envelope.id}/distribute`, - { - method: 'POST', - headers: { - 'Authorization': API_TOKEN, - 'Content-Type': 'application/json', - }, - } - ); + const distributeResponse = await fetch(`${BASE_URL}/envelope/distribute`, { + method: 'POST', + headers: { + 'Authorization': API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ envelopeId: envelope.id }), + }); if (!distributeResponse.ok) { const error = await distributeResponse.json(); @@ -422,9 +419,12 @@ echo "Created envelope: ${ENVELOPE_ID}" # Step 2: Send the document for signing echo "Sending document..." -curl -s -X POST "${BASE_URL}/envelope/${ENVELOPE_ID}/distribute" \ +curl -s -X POST "${BASE_URL}/envelope/distribute" \ -H "Authorization: ${API_TOKEN}" \ - -H "Content-Type: application/json" + -H "Content-Type: application/json" \ + -d "{ + \"envelopeId\": \"${ENVELOPE_ID}\" + }" echo "Document sent for signing!" @@ -441,7 +441,7 @@ The API returns standard HTTP status codes and JSON error responses: | `400` | Bad request - check your request payload | | `401` | Unauthorized - invalid or missing API token | | `404` | Not found - resource doesn't exist | -| `429` | Rate limited - wait 60 seconds and retry | +| `429` | Rate limited - wait for the duration in the `Retry-After` header | | `500` | Server error - retry or contact support | ### Error Response Format @@ -485,7 +485,7 @@ The API returns standard HTTP status codes and JSON error responses: ### Handling Rate Limits -The API allows 1000 requests per minute per IP address. Your organisation may have its own lower rate limits. When rate limited, wait at least 60 seconds before retrying: +The API allows 1000 requests per minute per IP address. Your organisation may have its own lower rate limits. Every response includes `X-RateLimit-Remaining` and `X-RateLimit-Reset` (an epoch timestamp in seconds). When you receive a `429` response, read the `Retry-After` header and wait for that many seconds before retrying. See [Error Handling Patterns](/docs/developers/examples/common-workflows#error-handling-patterns) for a more complete retry strategy. ```javascript async function fetchWithRetry(url, options, maxRetries = 3) { @@ -493,8 +493,9 @@ async function fetchWithRetry(url, options, maxRetries = 3) { const response = await fetch(url, options); if (response.status === 429) { - console.log('Rate limited, waiting 60 seconds...'); - await new Promise((resolve) => setTimeout(resolve, 60000)); + const retryAfterSeconds = Number.parseInt(response.headers.get('Retry-After') ?? '1', 10); + console.log(`Rate limited, waiting ${retryAfterSeconds} seconds...`); + await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1000)); continue; }