🔧Troubleshooting Recipe

Comprehensive guide to debugging and resolving common issues across all Docs-Dispatcher services.

Overview

This troubleshooting recipe helps you:

Diagnose common problems quickly
Understand error messages and codes
Debug template rendering issues
Fix provider connection problems
Resolve authentication failures
Handle rate limiting and timeouts
Analyze logs effectively

Quick Diagnostic Checklist

Start here when something goes wrong:

□ Is my Basic Auth credentials valid and not expired?
□ Did I validate the request first?
□ Is the provider configured correctly?
□ Does the template exist and is it accessible?
□ Are all required fields present?
□ Is the data in the correct format?
□ Did I check the error response for details?
□ Have I reviewed recent API changes?

Common Issues by Category

Authentication Issues

Issue 1: "Invalid or expired Basic Auth credentials"

Symptoms:

401 Unauthorized response
Message: "Invalid or expired Basic Auth credentials"
All API calls failing with auth error

Causes:

Token expired (120 minute lifetime)
Token malformed or corrupted
Wrong token used
System clock skew

Solutions:

// Check token expiration
function isTokenExpired(expiresAt) {
  const expiryDate = new Date(expiresAt);
  const now = new Date();
  const minutesUntilExpiry = (expiryDate - now) / 1000 / 60;

  console.log(`Token expires in ${minutesUntilExpiry} minutes`);
  return minutesUntilExpiry <= 0;
}

// Auto-refresh before expiry
async function ensureValidToken() {
  if (isTokenExpired(tokenExpiresAt)) {
    console.log('Token expired, refreshing...');
    await refreshJwtToken();
  }
  return jwtToken;
}

// Add 10-minute buffer
function shouldRefreshToken(expiresAt) {
  const expiryDate = new Date(expiresAt);
  const now = new Date();
  const minutesUntilExpiry = (expiryDate - now) / 1000 / 60;

  return minutesUntilExpiry < 10; // Refresh 10 min before expiry
}

Prevention:

Store token expiration time
Refresh tokens proactively (10 min before expiry)
Implement automatic retry with fresh token
Use token management library

Issue 2: "Authentication failed"

Symptoms:

401 Unauthorized response
Invalid credentials message
Basic Auth header rejected

Solutions:

Verify credentials:

# Test with curl (Basic Auth)
curl -X GET https://api.docs-dispatcher.io/api/v1/users/me \
  -u "[email protected]:your-password" \
  -v  # Verbose mode for debugging

Check for special characters in password:

// Properly encode Basic Auth credentials
const email = email.trim();
const password = password; // Don't trim passwords!
const authHeader = 'Basic ' + Buffer.from(`${email}:${password}`).toString('base64');

Verify account status:

Account active?
Email verified?
Correct company/environment?

Template Issues

Issue 3: "Template not found"

Symptoms:

404 error
Message: "Template with ID XXX not found"

Debugging steps:

# 1. Verify template exists
curl -X GET https://api.docs-dispatcher.io/api/v1/templates/123 \
  -u "$EMAIL:$PASSWORD"

# 2. Check template belongs to your company
curl -X GET https://api.docs-dispatcher.io/api/v1/templates \
  -u "$EMAIL:$PASSWORD" \
  | jq '.[] | select(.id == 123)'

# 3. Verify user has access
curl -X GET https://api.docs-dispatcher.io/api/v1/users/me \
  -u "$EMAIL:$PASSWORD" \
  | jq '.permissions'

Solutions:

Use correct template ID
Ensure template not deleted
Check user permissions
Verify company context

Issue 4: "Template rendering failed"

Symptoms:

Template data errors
Missing variables
Syntax errors in template

Common causes:

Missing required fields:

{
  "errors": [
    {
      "field": "template.data.customer.email",
      "message": "Required field missing"
    }
  ]
}

Solution:

// Validate template data
function validateTemplateData(data, schema) {
  const missing = [];

  for (const field of schema.required) {
    if (!getNestedValue(data, field)) {
      missing.push(field);
    }
  }

  if (missing.length > 0) {
    throw new Error(`Missing required fields: ${missing.join(', ')}`);
  }

  return true;
}

function getNestedValue(obj, path) {
  return path.split('.').reduce((current, prop) => current?.[prop], obj);
}

Wrong data types:

// Ensure correct types
const templateData = {
  invoiceNumber: String(invoiceNumber), // Convert to string
  date: formatDate(date), // Use proper date format
  total: Number(total), // Ensure number
  items: Array.isArray(items) ? items : [items] // Ensure array
};

Template syntax errors:

Check template syntax:

{{! Valid Mustache syntax }}
{{invoiceNumber}}
{{#items}}
  {{description}}: {{total}}
{{/items}}

{{! Invalid - will cause errors }}
{{invoiceNumber  // Missing closing braces
{{{items}}}      // Triple braces for unescaped HTML

Debug template rendering:

async function debugTemplateRendering(templateId, data) {
  try {
    // 1. Fetch template
    const template = await getTemplate(templateId);
    console.log('Template fetched:', template.name);

    // 2. Log template data
    console.log('Template data:', JSON.stringify(data, null, 2));

    // 3. Validate data against template
    const validation = await validateTemplate(templateId, data);
    console.log('Validation result:', validation);

    // 4. Test render
    const rendered = await renderTemplate(templateId, data);
    console.log('Rendered successfully, size:', rendered.length, 'bytes');

    return rendered;

  } catch (error) {
    console.error('Template rendering failed:');
    console.error('Error:', error.message);
    console.error('Stack:', error.stack);
    throw error;
  }
}

Provider Issues

Issue 5: "Provider not configured"

Symptoms:

Error: "Provider configuration missing"
Can't dispatch to provider

Solutions:

Check provider configuration:

# Get user configurations
curl -X GET https://api.docs-dispatcher.io/api/v1/users/me/configs \
  -u "$EMAIL:$PASSWORD"

# Get company configurations
curl -X GET https://api.docs-dispatcher.io/api/v1/companies/me/configs \
  -u "$EMAIL:$PASSWORD"

Verify provider credentials:

API keys valid?
Provider account active?
Correct environment (sandbox vs production)?

Create configuration:

async function ensureProviderConfigured(providerName) {
  // Check if configured
  const configs = await getUserConfigs();
  const providerConfig = configs.find(c => c.provider === providerName);

  if (!providerConfig) {
    console.error(`Provider ${providerName} not configured`);
    console.log('Please configure in Templater UI or via API');
    throw new Error(`Provider ${providerName} not configured`);
  }

  // Verify configuration is valid
  if (!providerConfig.credentials || !providerConfig.enabled) {
    throw new Error(`Provider ${providerName} configuration incomplete or disabled`);
  }

  return providerConfig;
}

Issue 6: "Provider API error"

Symptoms:

422 Unprocessable Entity
Provider-specific error codes
External API failures

Common provider errors:

Qonto - Duplicate invoice:

{
  "providerError": {
    "code": "DUPLICATE_INVOICE",
    "message": "Invoice INV-2026-001 already exists"
  }
}

Solution:

function generateUniqueInvoiceNumber() {
  const timestamp = Date.now();
  const random = Math.floor(Math.random() * 1000);
  return `INV-${timestamp}-${random}`;
}

PennyLane - Missing SIRET:

{
  "providerError": {
    "code": "MISSING_SIRET",
    "message": "SIRET required for French B2B invoices"
  }
}

Solution:

function validateFrenchInvoiceData(data) {
  if (data.customer.country === 'FR' && data.documentType === 'E_INVOICE') {
    if (!data.customer.siret) {
      throw new Error('SIRET required for French B2B e-invoices');
    }
  }
  return true;
}

Validation Issues

Issue 7: "Validation failed"

Symptoms:

400 Bad Request
Validation errors array in response

Debug validation errors:

async function debugValidation(requestData) {
  console.log('=== Validation Debug ===');

  // Validate
  const validation = await validateRequest(requestData);

  if (!validation.valid) {
    console.error('Validation failed with', validation.errors.length, 'errors:');

    validation.errors.forEach((error, index) => {
      console.error(`\nError ${index + 1}:`);
      console.error('  Field:', error.field);
      console.error('  Message:', error.message);
      console.error('  Current value:', error.value);
      console.error('  Expected:', error.expected);

      // Show path to field
      const fieldPath = error.field.split('.');
      console.error('  Path:', fieldPath.join(' → '));

      // Show nested value
      const currentValue = getNestedValue(requestData, error.field);
      console.error('  Actual value in request:', currentValue);
    });

    // Suggest fixes
    console.log('\n=== Suggested Fixes ===');
    validation.errors.forEach(error => {
      console.log(`- ${error.field}: ${getSuggestion(error)}`);
    });

    return false;
  }

  console.log('✓ Validation passed');

  if (validation.warnings?.length > 0) {
    console.warn('\n=== Warnings ===');
    validation.warnings.forEach(warn => {
      console.warn(`- ${warn.field}: ${warn.message}`);
    });
  }

  return true;
}

function getSuggestion(error) {
  const suggestions = {
    'Invalid email format': 'Use valid email: [email protected]',
    'Required field missing': `Add ${error.field} to your request`,
    'Invalid date format': 'Use ISO 8601 format: YYYY-MM-DD',
    'Amount must be positive': 'Ensure amount > 0'
  };

  return suggestions[error.message] || 'Check field value';
}

Rate Limiting

Issue 8: "Rate limit exceeded"

Symptoms:

429 Too Many Requests
Message: "Rate limit exceeded"
Retry-After header present

Solutions:

// Exponential backoff with retry
async function dispatchWithRetry(requestData, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await dispatch(requestData);
      return response;

    } catch (error) {
      if (error.status === 429) {
        const retryAfter = error.headers['retry-after'] || Math.pow(2, attempt);
        const delayMs = retryAfter * 1000;

        console.warn(`Rate limited. Retry attempt ${attempt + 1} after ${retryAfter}s`);

        await new Promise(resolve => setTimeout(resolve, delayMs));
        continue;
      }

      throw error;
    }
  }

  throw new Error('Max retries exceeded');
}

// Rate limiting queue
class RateLimitedQueue {
  constructor(maxPerMinute) {
    this.maxPerMinute = maxPerMinute;
    this.queue = [];
    this.processing = false;
    this.requestsThisMinute = 0;
    this.minuteStart = Date.now();
  }

  async add(fn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ fn, resolve, reject });
      this.process();
    });
  }

  async process() {
    if (this.processing || this.queue.length === 0) return;

    this.processing = true;

    while (this.queue.length > 0) {
      // Reset counter every minute
      const now = Date.now();
      if (now - this.minuteStart >= 60000) {
        this.requestsThisMinute = 0;
        this.minuteStart = now;
      }

      // Wait if at limit
      if (this.requestsThisMinute >= this.maxPerMinute) {
        const waitMs = 60000 - (now - this.minuteStart);
        console.log(`Rate limit reached, waiting ${waitMs}ms`);
        await new Promise(resolve => setTimeout(resolve, waitMs));
        continue;
      }

      // Process next request
      const { fn, resolve, reject } = this.queue.shift();
      this.requestsThisMinute++;

      try {
        const result = await fn();
        resolve(result);
      } catch (error) {
        reject(error);
      }
    }

    this.processing = false;
  }
}

// Usage
const queue = new RateLimitedQueue(100); // 100 requests per minute

async function sendInvoice(data) {
  return queue.add(() => dispatch(data));
}

Timeout Issues

Issue 9: "Request timeout"

Symptoms:

504 Gateway Timeout
Operation took > 120 seconds
No response received

Solutions:

Use async mode:

// Instead of sync (may timeout):
await dispatch(requestData);

// Use async mode:
const result = await dispatch(requestData, { async: true });
console.log('Queued:', result.dispatchId);
// Get result via webhook

Reduce document complexity:

// Split large requests
function splitLargeRequest(items) {
  const chunks = [];
  const chunkSize = 50; // Max items per request

  for (let i = 0; i < items.length; i += chunkSize) {
    chunks.push(items.slice(i, i + chunkSize));
  }

  return chunks;
}

// Process chunks
async function processLargeInvoice(invoice) {
  if (invoice.items.length > 50) {
    const chunks = splitLargeRequest(invoice.items);

    for (const chunk of chunks) {
      await dispatch({
        ...invoice,
        items: chunk
      });
    }
  } else {
    await dispatch(invoice);
  }
}

Optimize template:

Reduce template size
Minimize complex calculations
Optimize images
Reduce page count

Network Issues

Issue 10: "Network error"

Symptoms:

Connection refused
DNS lookup failed
SSL/TLS errors

Debugging:

# Test connectivity
curl -I https://api.docs-dispatcher.io/health

# Check DNS
nslookup api.docs-dispatcher.io

# Test SSL
openssl s_client -connect api.docs-dispatcher.io:443

# Verbose request
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -u "$EMAIL:$PASSWORD" \
  -v \
  --trace-ascii trace.log

Solutions:

Check firewall rules
Verify DNS settings
Update SSL certificates
Check proxy configuration

Data Issues

Issue 11: "Calculation mismatch"

Symptoms:

Total doesn't match sum
Tax calculation errors
Rounding issues

Solutions:

// Safe decimal math
function calculateInvoiceTotals(items, taxRate) {
  // Use decimal library for precision
  const Decimal = require('decimal.js');

  let subtotal = new Decimal(0);

  items.forEach(item => {
    const itemTotal = new Decimal(item.quantity)
      .times(item.unitPrice)
      .toDecimalPlaces(2);

    item.total = itemTotal.toNumber();
    subtotal = subtotal.plus(itemTotal);
  });

  const taxAmount = subtotal
    .times(taxRate)
    .toDecimalPlaces(2);

  const total = subtotal
    .plus(taxAmount)
    .toDecimalPlaces(2);

  return {
    subtotal: subtotal.toNumber(),
    taxAmount: taxAmount.toNumber(),
    total: total.toNumber()
  };
}

// Validate calculations
function validateCalculations(invoice) {
  const { subtotal, taxAmount, total, items, taxRate } = invoice;

  // Check items sum
  const calculatedSubtotal = items.reduce((sum, item) => sum + item.total, 0);
  if (Math.abs(calculatedSubtotal - subtotal) > 0.01) {
    throw new Error(`Subtotal mismatch: ${calculatedSubtotal} vs ${subtotal}`);
  }

  // Check tax
  const calculatedTax = Math.round(subtotal * taxRate * 100) / 100;
  if (Math.abs(calculatedTax - taxAmount) > 0.01) {
    throw new Error(`Tax mismatch: ${calculatedTax} vs ${taxAmount}`);
  }

  // Check total
  const calculatedTotal = subtotal + taxAmount;
  if (Math.abs(calculatedTotal - total) > 0.01) {
    throw new Error(`Total mismatch: ${calculatedTotal} vs ${total}`);
  }

  return true;
}

Debug Checklist

Use this systematic approach:

1. Enable Verbose Logging

const DEBUG = process.env.DEBUG === 'true';

function log(level, message, data) {
  if (!DEBUG && level === 'debug') return;

  const timestamp = new Date().toISOString();
  console.log(`[${timestamp}] [${level.toUpperCase()}] ${message}`);

  if (data) {
    console.log(JSON.stringify(data, null, 2));
  }
}

// Usage
log('debug', 'Request data', requestData);
log('info', 'Dispatching invoice');
log('error', 'Dispatch failed', error);

2. Capture Full Error Context

function handleError(error, context) {
  const errorDetails = {
    message: error.message,
    stack: error.stack,
    statusCode: error.status,
    context: context,
    timestamp: new Date().toISOString(),
    environment: process.env.NODE_ENV,
    version: process.env.APP_VERSION
  };

  // Log full context
  console.error('=== Error Details ===');
  console.error(JSON.stringify(errorDetails, null, 2));

  // Send to error tracking
  errorTracker.capture(errorDetails);

  return errorDetails;
}

// Usage
try {
  await dispatch(requestData);
} catch (error) {
  handleError(error, {
    operation: 'invoice_dispatch',
    invoiceNumber: requestData.template.data.invoiceNumber,
    provider: requestData.providerName
  });
}

3. Test in Isolation

// Test each component separately
async function testComponents() {
  console.log('=== Component Tests ===');

  // Test 1: Authentication
  try {
    const token = await authenticate();
    console.log('✓ Authentication: OK');
  } catch (error) {
    console.error('✗ Authentication: FAILED', error.message);
    return;
  }

  // Test 2: Template access
  try {
    const template = await getTemplate(123);
    console.log('✓ Template access: OK');
  } catch (error) {
    console.error('✗ Template access: FAILED', error.message);
    return;
  }

  // Test 3: Provider configuration
  try {
    const config = await getProviderConfig('qonto');
    console.log('✓ Provider config: OK');
  } catch (error) {
    console.error('✗ Provider config: FAILED', error.message);
    return;
  }

  // Test 4: Validation
  try {
    const validation = await validateRequest(testData);
    console.log('✓ Validation: OK');
  } catch (error) {
    console.error('✗ Validation: FAILED', error.message);
    return;
  }

  console.log('\n✓ All components working');
}

Getting Help

Before Contacting Support

Gather this information:

function collectDebugInfo() {
  return {
    // Environment
    environment: process.env.NODE_ENV,
    platform: process.platform,
    nodeVersion: process.version,

    // Request details
    dispatchId: result?.dispatchId,
    timestamp: new Date().toISOString(),

    // Error details
    errorMessage: error.message,
    errorCode: error.code,
    statusCode: error.status,

    // Configuration
    providerName: requestData.providerName,
    templateId: requestData.template.id,

    // Response (if any)
    response: JSON.stringify(response, null, 2)
  };
}

Contact Support

Email: [email protected]

Include:

Debug information (from above)
Steps to reproduce
Expected vs actual behavior
Request/response examples
Timestamps

Summary

Common issues:

✅ Token expiration - Refresh proactively
✅ Template errors - Validate data schema
✅ Provider errors - Check configuration
✅ Validation failures - Debug field by field
✅ Rate limiting - Implement backoff
✅ Timeouts - Use async mode
✅ Calculation errors - Use decimal math

Best practices:

Always validate before dispatch
Enable verbose logging in development
Test components in isolation
Implement proper error handling
Use async mode for production
Monitor rate limits
Keep tokens fresh

When stuck:

Review this troubleshooting guide
Check recent API updates
Test with minimal request
Enable debug logging
Contact support with full context

Happy debugging!

PreviousPostal Dispatch NextProviders Overview

Last updated 5 days ago

hashtagOverview

hashtagQuick Diagnostic Checklist

hashtagCommon Issues by Category

hashtagAuthentication Issues

hashtagIssue 1: "Invalid or expired Basic Auth credentials"

hashtagIssue 2: "Authentication failed"

hashtagTemplate Issues

hashtagIssue 3: "Template not found"

hashtagIssue 4: "Template rendering failed"

hashtagProvider Issues

hashtagIssue 5: "Provider not configured"

hashtagIssue 6: "Provider API error"

hashtagValidation Issues

hashtagIssue 7: "Validation failed"

hashtagRate Limiting

hashtagIssue 8: "Rate limit exceeded"

hashtagTimeout Issues

hashtagIssue 9: "Request timeout"

hashtagNetwork Issues

hashtagIssue 10: "Network error"

hashtagData Issues

hashtagIssue 11: "Calculation mismatch"

hashtagDebug Checklist

hashtag1. Enable Verbose Logging

hashtag2. Capture Full Error Context

hashtag3. Test in Isolation

hashtagGetting Help

hashtagBefore Contacting Support

hashtagContact Support

hashtagSummary

Overview

Quick Diagnostic Checklist

Common Issues by Category

Authentication Issues

Issue 1: "Invalid or expired Basic Auth credentials"

Issue 2: "Authentication failed"

Template Issues

Issue 3: "Template not found"

Issue 4: "Template rendering failed"

Provider Issues

Issue 5: "Provider not configured"

Issue 6: "Provider API error"

Validation Issues

Issue 7: "Validation failed"

Rate Limiting

Issue 8: "Rate limit exceeded"

Timeout Issues

Issue 9: "Request timeout"

Network Issues

Issue 10: "Network error"

Data Issues

Issue 11: "Calculation mismatch"

Debug Checklist

1. Enable Verbose Logging

2. Capture Full Error Context

3. Test in Isolation

Getting Help

Before Contacting Support

Contact Support

Summary