Error Codes — API Reference | Document Stack Docs

Error Response Format

When an API request fails, the response always includes success: false and an error message:

Error Response

{
  "success": false,
  "error": "Template not found"
}

The HTTP status code indicates the category of error, and the error field provides a human-readable description.

HTTP Status Codes

Code	Meaning	Common Cause
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid JSON, missing required fields, validation error
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	API key lacks permissions for this action
`404`	Not Found	Template, project, or resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error — contact support

Validation Errors

When the request body fails validation, the API returns a 400 status with details about what went wrong:

Validation Error

{
  "success": false,
  "error": "Validation failed: templateId is required"
}

Handling Errors in Code

Always check the success field or HTTP status code before processing the response:

Error Handling Example

import { DocumentStack } from "@document-stack/sdk-node";

const client = new DocumentStack({ apiKey: process.env.DS_API_KEY! });

try {
    const result = await client.generate({
        templateId: "tmpl_abc123",
        data: { name: "Alice" },
    });
    console.log("PDF URL:", result.url);
} catch (error) {
    if (error.status === 401) {
        console.error("Invalid API key — check your credentials");
    } else if (error.status === 404) {
        console.error("Template not found — verify the template ID");
    } else if (error.status === 429) {
        console.error("Rate limited — wait and retry");
    } else {
        console.error("Unexpected error:", error.message);
    }
}

Retry Strategy

For transient errors (429 and 5xx), implement exponential backoff:

Wait 1 second after the first failure
Wait 2 seconds after the second failure
Wait 4 seconds after the third failure
Stop retrying after 3–5 attempts

Retry-After Header

When rate-limited (429), check the Retry-After header for the exact number of seconds to wait before retrying.

Common Mistakes

Issue	Error	Fix
Missing `Authorization` header	401 Unauthorized	Add `Bearer YOUR_API_KEY` header
Wrong Content-Type	400 Bad Request	Set `Content-Type: application/json`
Template ID from another org	404 Not Found	Use a template ID belonging to the API key's org
Malformed JSON body	400 Bad Request	Validate JSON before sending

Next Steps

Rate Limits — Understand request quotas
Response Codes Reference — Full status code reference
Troubleshooting — Resolve common issues