❌Common Errors

Complete reference for HTTP errors, error codes, and solutions in Docs-Dispatcher.

Overview

This guide covers:

HTTP status codes (400-503)
Error response structure
Provider-specific errors
Template errors
Authentication errors
Validation errors
Solutions with code examples

Error Response Structure

All errors follow a consistent format:

{
  "error": "error_code",
  "message": "Human-readable error description",
  "details": {
    "field": "specific.field.path",
    "value": "actual_value",
    "expected": "expected_value"
  },
  "timestamp": "2026-02-13T10:30:00Z",
  "path": "/api/invoicing",
  "requestId": "req_abc123xyz"
}

Field

Description

error

Machine-readable error code

message

Human-readable description

details

Additional context (optional)

timestamp

When error occurred

path

API endpoint that failed

requestId

For support tracking

HTTP Status Codes

400 Bad Request

Meaning: Request is malformed or invalid.

Common Causes

1. Missing Required Field

{
  "error": "missing_required_field",
  "message": "Field 'documentType' is required",
  "details": {
    "field": "documentType",
    "requiredFor": "invoicing service"
  }
}

Solution:

// Ensure all required fields are present
const request = {
  documentType: 'INVOICE', // Required for invoicing
  providerName: 'qonto',
  template: {
    id: 123,
    data: {...}
  }
};

2. Invalid Field Type

{
  "error": "invalid_field_type",
  "message": "Field 'template.id' must be a number",
  "details": {
    "field": "template.id",
    "expectedType": "number",
    "actualType": "string",
    "value": "123"
  }
}

Solution:

// Convert string to number
template: {
  id: Number(templateId), // Not string "123"
  data: {...}
}

3. Invalid Enum Value

{
  "error": "invalid_enum_value",
  "message": "Invalid document type: 'RECEIPT'",
  "details": {
    "field": "documentType",
    "value": "RECEIPT",
    "validValues": ["INVOICE", "E_INVOICE", "QUOTE", "CREDIT"]
  }
}

Solution:

// Use valid enum values
const validDocumentTypes = ['INVOICE', 'E_INVOICE', 'QUOTE', 'CREDIT'];
const documentType = 'INVOICE'; // Must be one of valid values

4. Provider Not Configured

{
  "error": "provider_not_configured",
  "message": "No configuration found for provider 'qonto'",
  "details": {
    "provider": "qonto",
    "service": "invoicing",
    "userId": 123,
    "companyId": 456
  }
}

Solution:

// Check provider configuration
async function ensureProviderConfigured(providerName) {
  const configs = await fetch('/api/v1/users/me/configs', {
    headers: { 'Authorization': `Bearer ${jwt}` }
  }).then(r => r.json());

  const config = configs.find(c => c.providerName === providerName);

  if (!config) {
    throw new Error(
      `Provider ${providerName} not configured. ` +
      'Please configure in Templater UI at /admin/configs'
    );
  }

  if (!config.isActive) {
    throw new Error(`Provider ${providerName} is disabled`);
  }

  return config;
}

5. Invalid Provider for Service

{
  "error": "invalid_provider",
  "message": "Provider 'qonto' is not supported for service 'sms'",
  "details": {
    "provider": "qonto",
    "service": "sms",
    "validProviders": ["brevo", "ovh", "sms_factor", "sms_magic"]
  }
}

Solution:

// Provider validation by service
const PROVIDER_MAP = {
  invoicing: ['ipaidthat', 'pennylane', 'qonto', 'superpdp'],
  esign: ['signaturit', 'universign', 'yousign'],
  postal: ['mysendingbox'],
  sms: ['brevo', 'ovh', 'sms_factor', 'sms_magic']
};

function validateProvider(service, provider) {
  const validProviders = PROVIDER_MAP[service];

  if (!validProviders.includes(provider)) {
    throw new Error(
      `Provider '${provider}' not valid for ${service}. ` +
      `Use one of: ${validProviders.join(', ')}`
    );
  }
}

401 Unauthorized

Meaning: Authentication failed or missing.

Common Causes

1. Missing JWT Token

{
  "error": "authentication_required",
  "message": "No authentication token provided"
}

Solution:

// Always include Authorization header
const response = await fetch('https://api.docs-dispatcher.io/api/invoicing', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${jwtToken}`, // Required
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(request)
});

2. Expired JWT Token

{
  "error": "token_expired",
  "message": "JWT token has expired",
  "details": {
    "expiredAt": "2026-02-13T08:30:00Z",
    "currentTime": "2026-02-13T10:30:00Z"
  }
}

Solution:

// Auto-refresh token before expiry
class TokenManager {
  constructor() {
    this.token = null;
    this.expiresAt = null;
  }

  async getToken() {
    // Refresh if expired or expiring soon (10 min buffer)
    if (!this.token || this.isExpiringSoon()) {
      await this.refreshToken();
    }
    return this.token;
  }

  isExpiringSoon() {
    if (!this.expiresAt) return true;
    const now = Date.now();
    const expiryTime = new Date(this.expiresAt).getTime();
    const minutesUntilExpiry = (expiryTime - now) / 1000 / 60;
    return minutesUntilExpiry < 10; // Refresh 10 min before expiry
  }

  async refreshToken() {
    const response = await fetch('https://api.docs-dispatcher.io/auth', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: process.env.DOCS_DISPATCHER_EMAIL,
        password: process.env.DOCS_DISPATCHER_PASSWORD
      })
    });

    const { token, expiresAt } = await response.json();
    this.token = token;
    this.expiresAt = expiresAt;
  }
}

// Usage
const tokenManager = new TokenManager();
const jwt = await tokenManager.getToken();

3. Invalid Token Format

{
  "error": "invalid_token",
  "message": "JWT token is malformed or invalid"
}

Solution:

// Verify token format
function validateJwtFormat(token) {
  // JWT format: header.payload.signature
  const parts = token.split('.');

  if (parts.length !== 3) {
    throw new Error('Invalid JWT format. Expected format: xxx.yyy.zzz');
  }

  try {
    // Decode payload to verify it's valid base64
    const payload = JSON.parse(atob(parts[1]));
    console.log('Token valid for user:', payload.email);
    return true;
  } catch (error) {
    throw new Error('Token payload is not valid JSON');
  }
}

403 Forbidden

Meaning: Authenticated but not authorized for this resource.

Common Causes

1. Insufficient Permissions

{
  "error": "insufficient_permissions",
  "message": "User does not have permission to access this resource",
  "details": {
    "requiredPermission": "templates:write",
    "userPermissions": ["templates:read"]
  }
}

Solution:

// Check user permissions before operation
async function checkPermission(requiredPermission) {
  const user = await fetch('/api/v1/users/me', {
    headers: { 'Authorization': `Bearer ${jwt}` }
  }).then(r => r.json());

  if (!user.permissions.includes(requiredPermission)) {
    throw new Error(
      `Missing permission: ${requiredPermission}. ` +
      'Contact your administrator to grant access.'
    );
  }
}

2. Template Access Denied

{
  "error": "template_access_denied",
  "message": "Template 123 does not belong to your company",
  "details": {
    "templateId": 123,
    "templateCompanyId": 456,
    "userCompanyId": 789
  }
}

Solution:

// List user's accessible templates
async function getUserTemplates() {
  const templates = await fetch('/api/v1/templates', {
    headers: { 'Authorization': `Bearer ${jwt}` }
  }).then(r => r.json());

  return templates.map(t => ({
    id: t.id,
    name: t.name,
    companyId: t.companyId
  }));
}

404 Not Found

Meaning: Resource does not exist.

Common Causes

1. Template Not Found

{
  "error": "template_not_found",
  "message": "Template with ID 999 not found",
  "details": {
    "templateId": 999
  }
}

Solution:

// Verify template exists before use
async function validateTemplate(templateId) {
  try {
    const template = await fetch(
      `https://api.docs-dispatcher.io/api/v1/templates/${templateId}`,
      { headers: { 'Authorization': `Bearer ${jwt}` } }
    );

    if (!template.ok) {
      throw new Error(`Template ${templateId} not found or not accessible`);
    }

    return await template.json();
  } catch (error) {
    console.error('Template validation failed:', error.message);
    throw error;
  }
}

2. Endpoint Not Found

{
  "error": "not_found",
  "message": "Endpoint /api/invalid does not exist",
  "details": {
    "path": "/api/invalid",
    "method": "POST"
  }
}

Solution:

// Use correct endpoints
const VALID_ENDPOINTS = {
  invoicing: '/api/invoicing',
  esign: '/api/esign',
  postal: '/api/postal',
  sms: '/api/sms',
  email: '/api/email',
  file: '/api/file',
  upload: '/api/upload'
};

function getEndpoint(service) {
  const endpoint = VALID_ENDPOINTS[service];
  if (!endpoint) {
    throw new Error(
      `Invalid service: ${service}. ` +
      `Valid services: ${Object.keys(VALID_ENDPOINTS).join(', ')}`
    );
  }
  return `https://api.docs-dispatcher.io${endpoint}`;
}

409 Conflict

Meaning: Request conflicts with existing resource.

Common Causes

1. Duplicate Invoice Number

{
  "error": "duplicate_invoice",
  "message": "Invoice INV-2026-001 already exists",
  "details": {
    "invoiceNumber": "INV-2026-001",
    "existingInvoiceId": "qonto_inv_123"
  }
}

Solution:

// Generate unique invoice numbers
function generateInvoiceNumber() {
  const date = new Date();
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const timestamp = Date.now();
  const random = Math.floor(Math.random() * 1000);

  return `INV-${year}${month}-${timestamp}-${random}`;
}

// Or check for uniqueness
async function ensureUniqueInvoiceNumber(number) {
  const exists = await checkInvoiceExists(number);

  if (exists) {
    // Append suffix
    return `${number}-${Date.now()}`;
  }

  return number;
}

415 Unsupported Media Type

Meaning: Content-Type header is incorrect.

{
  "error": "unsupported_media_type",
  "message": "Content-Type must be application/json",
  "details": {
    "received": "text/plain",
    "expected": "application/json"
  }
}

Solution:

// Always set correct Content-Type
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${jwt}`,
    'Content-Type': 'application/json' // Required
  },
  body: JSON.stringify(data) // Must be JSON string
});

417 Expectation Failed

Meaning: Provider-specific requirement not met.

{
  "error": "provider_validation_failed",
  "message": "Provider rejected request: Missing SIRET for French B2B invoice",
  "details": {
    "provider": "pennylane",
    "providerError": {
      "code": "MISSING_SIRET",
      "message": "SIRET required for French B2B e-invoices"
    }
  }
}

Solution:

// Validate provider-specific requirements
function validateFrenchInvoice(data) {
  if (data.documentType === 'E_INVOICE' && data.customer.country === 'FR') {
    if (!data.customer.siret) {
      throw new Error(
        'SIRET number required for French B2B e-invoices. ' +
        'Add customer.siret to template data.'
      );
    }

    // Validate SIRET format (14 digits)
    if (!/^\d{14}$/.test(data.customer.siret)) {
      throw new Error('SIRET must be 14 digits');
    }
  }
}

422 Unprocessable Entity

Meaning: Request syntax valid but semantically incorrect.

Common Causes

1. Validation Errors

{
  "error": "validation_failed",
  "message": "Request validation failed",
  "details": {
    "errors": [
      {
        "field": "template.data.dueDate",
        "message": "Due date must be after invoice date",
        "value": "2026-01-01",
        "constraint": "dueDate > invoiceDate"
      },
      {
        "field": "template.data.total",
        "message": "Total does not match subtotal + tax",
        "expected": 1800.00,
        "actual": 1700.00
      }
    ]
  }
}

Solution:

// Validate business rules
function validateInvoiceDates(invoiceDate, dueDate) {
  const invoice = new Date(invoiceDate);
  const due = new Date(dueDate);

  if (due <= invoice) {
    throw new Error(
      `Due date (${dueDate}) must be after invoice date (${invoiceDate})`
    );
  }

  // Warn if due date is too far in future
  const daysDiff = (due - invoice) / (1000 * 60 * 60 * 24);
  if (daysDiff > 90) {
    console.warn(`Warning: Due date is ${daysDiff} days in future`);
  }
}

function validateInvoiceCalculations(items, subtotal, tax, total) {
  const calculatedSubtotal = items.reduce((sum, item) =>
    sum + (item.quantity * item.unitPrice), 0
  );

  if (Math.abs(calculatedSubtotal - subtotal) > 0.01) {
    throw new Error(
      `Subtotal mismatch: calculated ${calculatedSubtotal}, ` +
      `provided ${subtotal}`
    );
  }

  const calculatedTotal = subtotal + tax;
  if (Math.abs(calculatedTotal - total) > 0.01) {
    throw new Error(
      `Total mismatch: calculated ${calculatedTotal}, ` +
      `provided ${total}`
    );
  }
}

2. Template Schema Mismatch

{
  "error": "template_schema_mismatch",
  "message": "Template data does not match template schema",
  "details": {
    "missingFields": ["customer.email", "items[0].description"],
    "invalidFields": {
      "total": "Expected number, got string"
    }
  }
}

Solution:

// Validate against template schema
async function validateTemplateData(templateId, data) {
  const template = await getTemplate(templateId);
  const schema = template.dataSchema;

  const errors = [];

  // Check required fields
  for (const field of schema.required || []) {
    const value = getNestedValue(data, field);
    if (value === undefined || value === null) {
      errors.push(`Missing required field: ${field}`);
    }
  }

  // Check field types
  for (const [field, type] of Object.entries(schema.types || {})) {
    const value = getNestedValue(data, field);
    if (value !== undefined && typeof value !== type) {
      errors.push(
        `Field '${field}': expected ${type}, got ${typeof value}`
      );
    }
  }

  if (errors.length > 0) {
    throw new Error(`Template validation failed:\n${errors.join('\n')}`);
  }
}

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

429 Too Many Requests

Meaning: Rate limit exceeded.

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit of 100 requests per minute exceeded",
  "details": {
    "limit": 100,
    "period": "1 minute",
    "retryAfter": 45
  }
}

Solution:

// Implement exponential backoff
async function fetchWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = response.headers.get('retry-after') ||
                          Math.pow(2, attempt);
        const delayMs = retryAfter * 1000;

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

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

      return response;

    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await new Promise(resolve =>
        setTimeout(resolve, Math.pow(2, attempt) * 1000)
      );
    }
  }

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

500 Internal Server Error

Meaning: Server-side error occurred.

{
  "error": "internal_error",
  "message": "An unexpected error occurred",
  "requestId": "req_abc123xyz"
}

Solution:

// Log error details and retry
async function handleServerError(error, requestData) {
  console.error('Server error occurred:', {
    error: error.message,
    requestId: error.requestId,
    timestamp: new Date().toISOString(),
    request: requestData
  });

  // Send to error tracking
  errorTracker.capture({
    level: 'error',
    message: '500 Internal Server Error',
    context: {
      requestId: error.requestId,
      endpoint: requestData.endpoint
    }
  });

  // Retry once after delay
  console.log('Retrying after 5 seconds...');
  await new Promise(resolve => setTimeout(resolve, 5000));

  try {
    return await dispatch(requestData);
  } catch (retryError) {
    // If retry fails, contact support
    throw new Error(
      `Server error persists. Request ID: ${error.requestId}. ` +
      'Contact [email protected]'
    );
  }
}

501 Not Implemented

Meaning: Feature not yet implemented.

{
  "error": "not_implemented",
  "message": "Feature 'bulk_dispatch' is not yet implemented"
}

503 Service Unavailable

Meaning: Service temporarily unavailable (maintenance, overload).

{
  "error": "service_unavailable",
  "message": "Service temporarily unavailable. Please try again later.",
  "details": {
    "retryAfter": 300
  }
}

Solution:

// Check API status and wait
async function waitForService() {
  const statusUrl = 'https://api.docs-dispatcher.io/health';

  for (let i = 0; i < 10; i++) {
    try {
      const response = await fetch(statusUrl);
      if (response.ok) {
        console.log('Service available');
        return true;
      }
    } catch (error) {
      console.log(`Service check ${i + 1}/10 failed`);
    }

    await new Promise(resolve => setTimeout(resolve, 30000)); // Wait 30s
  }

  throw new Error('Service still unavailable after 5 minutes');
}

Error Code Reference

Quick lookup table for all error codes:

Code

Status

Provider-Specific Errors

Qonto

Duplicate Invoice:

{
  "providerError": {
    "code": "DUPLICATE_INVOICE",
    "message": "Invoice number already exists"
  }
}

Invalid Organization:

{
  "providerError": {
    "code": "INVALID_ORG",
    "message": "Organization slug not found"
  }
}

PennyLane

Missing SIRET:

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

Brevo (SMS)

Invalid Phone Number:

{
  "providerError": {
    "code": "INVALID_RECIPIENT",
    "message": "Phone number format invalid"
  }
}

Universign (eSign)

Invalid Signer:

{
  "providerError": {
    "code": "INVALID_SIGNER",
    "message": "Signer email format invalid"
  }
}

Debugging Workflow

When you encounter an error:

Check HTTP status code - Identifies error category
Read error.message - Human-readable description
Examine error.details - Specific context
Look up error code - Find solution in this guide
Check requestId - For support tickets
Review request data - Find what's wrong
Validate before retry - Use /validate endpoint

// Complete error handling example
async function dispatchWithErrorHandling(requestData) {
  try {
    // 1. Validate first
    const validation = await fetch(
      'https://api.docs-dispatcher.io/api/invoicing/validate',
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${jwt}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(requestData)
      }
    ).then(r => r.json());

    if (!validation.valid) {
      console.error('Validation failed:', validation.errors);
      throw new Error('Fix validation errors before dispatching');
    }

    // 2. Dispatch
    const response = await fetch(
      'https://api.docs-dispatcher.io/api/invoicing',
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${jwt}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(requestData)
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new DispatchError(error, response.status);
    }

    return await response.json();

  } catch (error) {
    return handleDispatchError(error, requestData);
  }
}

class DispatchError extends Error {
  constructor(errorData, status) {
    super(errorData.message);
    this.name = 'DispatchError';
    this.code = errorData.error;
    this.status = status;
    this.details = errorData.details;
    this.requestId = errorData.requestId;
  }
}

function handleDispatchError(error, requestData) {
  console.error('Dispatch failed:', {
    code: error.code,
    status: error.status,
    message: error.message,
    details: error.details,
    requestId: error.requestId
  });

  // Handle specific errors
  switch (error.code) {
    case 'token_expired':
      return refreshTokenAndRetry(requestData);

    case 'provider_not_configured':
      throw new Error(
        'Provider not configured. Visit ' +
        'https://app.docs-dispatcher.io/admin/configs'
      );

    case 'rate_limit_exceeded':
      return retryAfterDelay(requestData, error.details.retryAfter);

    case 'validation_failed':
      console.error('Validation errors:', error.details.errors);
      throw error;

    default:
      // Log and re-throw
      errorTracker.capture(error);
      throw error;
  }
}

Provider Issues - Provider-specific troubleshooting
Configuration Problems - Config resolution debugging
Debug Checklist - Systematic debugging workflow
Validation - Catch errors early

Summary

Key takeaways:

All errors follow consistent structure with error, message, details
HTTP status codes indicate error category (400s = client, 500s = server)
Always validate requests before dispatch to catch errors early
Implement proper error handling with retries and logging
Use requestId when contacting support
Check provider-specific requirements for 417/422 errors
Implement exponential backoff for 429 rate limits
Refresh JWT tokens proactively to avoid 401 errors

When stuck: Copy the error code and requestId, search this guide, and include both in support requests.

PreviousSDK Troubleshooting NextProvider Issues

Last updated 5 days ago

hashtagOverview

hashtagError Response Structure

hashtagHTTP Status Codes

hashtag400 Bad Request

hashtagCommon Causes

hashtag401 Unauthorized

hashtagCommon Causes

hashtag403 Forbidden

hashtagCommon Causes

hashtag404 Not Found

hashtagCommon Causes

hashtag409 Conflict

hashtagCommon Causes

hashtag415 Unsupported Media Type

hashtag417 Expectation Failed

hashtag422 Unprocessable Entity

hashtagCommon Causes

hashtag429 Too Many Requests

hashtag500 Internal Server Error

hashtag501 Not Implemented

hashtag503 Service Unavailable

hashtagError Code Reference

hashtagProvider-Specific Errors

hashtagQonto

hashtagPennyLane

hashtagBrevo (SMS)

hashtagUniversign (eSign)

hashtagDebugging Workflow

hashtagRelated Documentation

hashtagSummary

Overview

Error Response Structure

HTTP Status Codes

400 Bad Request

Common Causes

401 Unauthorized

Common Causes

403 Forbidden

Common Causes

404 Not Found

Common Causes

409 Conflict

Common Causes

415 Unsupported Media Type

417 Expectation Failed

422 Unprocessable Entity

Common Causes

429 Too Many Requests

500 Internal Server Error

501 Not Implemented

503 Service Unavailable

Error Code Reference

Provider-Specific Errors

Qonto

PennyLane

Brevo (SMS)

Universign (eSign)

Debugging Workflow

Related Documentation

Summary