🔧SDK Troubleshooting

This guide helps you resolve common issues when using the Docs-Dispatcher SDKs (Node.js, PHP, Java).

Authentication Errors

Invalid Token (401 Unauthorized)

Symptoms:

Status code: 401
Response: {"error": "Unauthorized", "message": "Invalid token"}

Causes:

Token is incorrect or malformed
Token has expired
Token was revoked or deleted
Using wrong authentication method (Bearer vs Basic)

Solutions:

Node.js:

// Verify you're using the correct token
import DocsDispatcher, { BearerAuth } from 'docs-dispatcher-sdk'
import axios from 'axios'

const auth = new BearerAuth('your-valid-jwt-token') // Check token value
const http = new DocsDispatcher.Http.AxiosAdapter(axios)
const dd = new DocsDispatcher(auth, http)

// Test authentication
try {
  await dd.healthCheck()
  console.log('Authentication successful')
} catch (error) {
  console.error('Auth failed:', error.message)
}

PHP:

use DocsDispatcherIo\Sdk\Authentication\BearerTokenAuthentication;
use DocsDispatcherIo\Sdk\Client;

// Verify token format
$token = getenv('DOCSDISPATCHER_TOKEN');
if (empty($token)) {
    throw new \Exception('Token not configured');
}

$authentication = new BearerTokenAuthentication($token);
$client = new Client($authentication);

Java:

ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setBasePath("https://api.docs-dispatcher.io");

// Verify token is set correctly
String token = System.getenv("DOCSDISPATCHER_TOKEN");
if (token == null || token.isEmpty()) {
    throw new IllegalStateException("Token not configured");
}

apiClient.setBearerToken(token);

Get a New Token:

Log in to Docs-Dispatcher dashboard
Navigate to Settings → API Tokens
Generate a new token
Update your environment variables

Expired Token

Symptoms:

Status code: 401
Response: {"error": "Token expired"}

Solution: Tokens have a validity period. Generate a new token from your dashboard and update your configuration.

Missing Authentication

Symptoms:

Status code: 401
Response: {"error": "Authentication required"}

Solution: Ensure you've configured authentication before making API calls.

Node.js:

// ❌ Wrong: No authentication
const dd = new DocsDispatcher()

// ✅ Correct: With authentication
const dd = DocsDispatcher.create({
  username: 'your-username',
  password: 'your-password'
})

PHP:

// ❌ Wrong: Client without authentication
$client = new Client();

// ✅ Correct: Client with authentication
$auth = new BearerTokenAuthentication($token);
$client = new Client($auth);

Java:

// ❌ Wrong: No token set
ApiClient apiClient = Configuration.getDefaultApiClient();

// ✅ Correct: Token configured
ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setBearerToken("your-token");

Validation Errors

Missing Required Parameters (400 Bad Request)

Symptoms:

Status code: 400
Response: {"error": "Validation failed", "details": ["Template name is required"]}

Causes:

Missing required fields
Invalid field types
Empty or null values for required parameters

Solutions:

Node.js (use built-in validation):

const invoice = new DocsDispatcher.Service.InvoiceDispatcher({
  customer,
  items,
  documentType: InvoiceDocumentType.INVOICE,
  issueDate: '2025-01-15'
})

// Validate before dispatching
const errors: ValidationError[] = []
const isValid = invoice.validate(errors)

if (!isValid) {
  console.error('Validation errors:', errors)
  // Output:
  // [
  //   { path: ['customer', 'email'], message: 'Customer email is required' },
  //   { path: ['items'], message: 'At least one item is required' }
  // ]
  return
}

await dd.withBaseService(invoice).dispatch()

PHP:

// Ensure all required fields are set
$customer = new InvoiceCustomer(
    CustomerTypes::COMPANY,
    '[email protected]', // Required
    $billingAddress     // Required
);

// Check for null/empty values
if (empty($customer->getEmail())) {
    throw new \InvalidArgumentException('Customer email is required');
}

if (empty($items)) {
    throw new \InvalidArgumentException('At least one item is required');
}

Java:

// Validate request data before dispatching
if (data.isEmpty()) {
    throw new IllegalArgumentException("Template data is required");
}

if (fileContent.getTemplateName() == null) {
    throw new IllegalArgumentException("Template name is required");
}

// Use validation endpoint
try {
    Object validationResult = endUserApi.dispatchersValidateRequest(
        Service.FILE,
        request
    );
} catch (ApiException e) {
    System.err.println("Validation failed: " + e.getResponseBody());
}

Invalid Data Types

Symptoms:

Status code: 400
Response: {"error": "Invalid type for field 'quantity': expected number, got string"}

Solution: Ensure you're using the correct data types.

Node.js:

// ❌ Wrong: String instead of number
.withQuantity('10')

// ✅ Correct: Number
.withQuantity(10)

PHP:

// ❌ Wrong: String instead of float
$item->setQuantity('10.5');

// ✅ Correct: Float
$item->setQuantity(10.5);

Java:

// ❌ Wrong: String in numeric field
data.put("amount", "150.00");

// ✅ Correct: Numeric type
data.put("amount", 150.00);

Template Not Found (404 Not Found)

Symptoms:

Status code: 404
Response: {"error": "Template not found", "templateName": "invoice-template"}

Causes:

Template name is misspelled
Template doesn't exist in your account
Template was deleted

Solutions:

Verify template name in Templater UI
Check for typos in template name
Ensure template is published (not draft)

Node.js:

// List available templates via API or dashboard
.setTemplateName('invoice-template') // Match exact name

PHP:

// Use exact template name from dashboard
$fileService->setTemplateName('invoice-template');

Java:

// Use exact template name
fileContent.setTemplateName("invoice-template");

Network and Connection Issues

Connection Timeout

Symptoms:

Error: connect ETIMEDOUT
Error: Read timed out

Causes:

Network connectivity issues
Firewall blocking outbound requests
API endpoint is down

Solutions:

Node.js (increase timeout):

import axios from 'axios'

const http = new DocsDispatcher.Http.AxiosAdapter(
  axios.create({
    timeout: 60000 // 60 seconds
  })
)
const dd = new DocsDispatcher(auth, http)

PHP (configure Guzzle timeout):

use GuzzleHttp\Client as GuzzleClient;

$guzzle = new GuzzleClient([
    'timeout' => 60,
    'connect_timeout' => 30
]);

$client = new Client($authentication, null, $guzzle);

Java (configure OkHttp timeout):

import okhttp3.OkHttpClient;
import java.util.concurrent.TimeUnit;

OkHttpClient httpClient = new OkHttpClient.Builder()
    .connectTimeout(30, TimeUnit.SECONDS)
    .readTimeout(60, TimeUnit.SECONDS)
    .writeTimeout(60, TimeUnit.SECONDS)
    .build();

ApiClient apiClient = new ApiClient(httpClient);

Check API Status: Visit status.docs-dispatcher.io to verify API availability.

SSL/TLS Certificate Errors

Symptoms:

Error: self signed certificate in certificate chain
Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE

Causes:

Corporate proxy with SSL inspection
Outdated CA certificates
Network security policies

Solutions:

Node.js (not recommended for production):

import https from 'https'
import axios from 'axios'

const http = new DocsDispatcher.Http.AxiosAdapter(
  axios.create({
    httpsAgent: new https.Agent({
      rejectUnauthorized: false // Only for testing!
    })
  })
)

Better Solution: Update CA certificates:

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew upgrade openssl

Rate Limiting (429 Too Many Requests)

Symptoms:

Status code: 429
Response: {"error": "Rate limit exceeded", "retryAfter": 60}

Solutions:

Implement Retry Logic:

Node.js:

async function dispatchWithRetry(dd, service, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await dd.withBaseService(service).dispatch()
    } catch (error) {
      if (error.code === 429 && i < maxRetries - 1) {
        const retryAfter = error.headers['retry-after'] || 60
        console.log(`Rate limited. Retrying in ${retryAfter}s...`)
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000))
      } else {
        throw error
      }
    }
  }
}

PHP:

function dispatchWithRetry($client, $serviceMediator, $format, $maxRetries = 3) {
    for ($i = 0; $i < $maxRetries; $i++) {
        try {
            return $client->executeRequest($serviceMediator, $format);
        } catch (ApiException $e) {
            if ($e->getCode() === 429 && $i < $maxRetries - 1) {
                $retryAfter = $e->getResponseHeaders()['retry-after'] ?? 60;
                echo "Rate limited. Retrying in {$retryAfter}s...\n";
                sleep($retryAfter);
            } else {
                throw $e;
            }
        }
    }
}

Installation Problems

Package Manager Errors

Node.js - Yarn/npm Issues:

# Clear cache and reinstall
rm -rf node_modules package-lock.json yarn.lock
yarn install
# or
npm install

PHP - Composer Issues:

# Clear cache and reinstall
composer clear-cache
rm -rf vendor composer.lock
composer install

Java - Maven Issues:

# Clear local repository and rebuild
mvn clean install -U
# or force update
mvn clean install -U -Dmaven.test.skip=true

Java - Gradle Issues:

# Clear cache and rebuild
./gradlew clean build --refresh-dependencies

Version Compatibility Issues

Node.js:

{
  "engines": {
    "node": "^22.0.0"
  }
}

PHP: Check PHP version:

php -v
# Should be >= 8.1 for SDK v0.2.x
# Use SDK v0.1.x for PHP 7.2-7.4

Java: Check Java version:

java -version
# Should be >= 1.8

Common Mistakes

Wrong Service Enum

Java:

// ❌ Wrong: Using string instead of enum
endUserApi.dispatchersDispatch("file", request);

// ✅ Correct: Using Service enum
endUserApi.dispatchersDispatch(Service.FILE, request);

Missing Config for Provider

Symptoms:

Status code: 417
Response: {"error": "Provider configuration not found", "provider": "ipaidthat"}

Solution: Configure the provider in your dashboard before using it.

Navigate to Admin → Configurations
Select the provider (e.g., iPaidThat, Qonto, SMS Factor)
Add API credentials
Save and test configuration

Incorrect Response Format

Symptoms:

Error: Unexpected token < in JSON at position 0

Cause: Requesting JSON format but API returns binary (PDF).

Solution:

Node.js:

// ✅ Correct: Request PDF format
file.setResultFormat(DocsDispatcher.RETURN_FORMATS.PDF)

PHP:

// ✅ Correct: Specify expected format
$response = $client->executeRequest($serviceMediator, 'application/pdf');

Java:

// ✅ Correct: Response is a File object
File result = endUserApi.dispatchersDispatch(Service.FILE, request);

Debug Logging

Enable detailed logging to diagnose issues:

Node.js

// Set environment variable
process.env.DEBUG = 'docs-dispatcher:*'

// Or enable in code
const dd = DocsDispatcher.create({
  username: 'your-username',
  password: 'your-password',
  debug: true
})

PHP

// Enable Guzzle debug output
use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;

$handlerStack = HandlerStack::create();
$handlerStack->push(Middleware::log(
    new \Monolog\Logger('guzzle'),
    new \Monolog\Formatter\LineFormatter()
));

$guzzle = new GuzzleClient([
    'handler' => $handlerStack,
    'debug' => true
]);

$client = new Client($authentication, null, $guzzle);

Java

// Enable SDK debugging
ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setDebugging(true);

// Enable OkHttp logging
import okhttp3.logging.HttpLoggingInterceptor;

HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
logging.setLevel(HttpLoggingInterceptor.Level.BODY);

OkHttpClient httpClient = new OkHttpClient.Builder()
    .addInterceptor(logging)
    .build();

ApiClient apiClient = new ApiClient(httpClient);

Environment-Specific Issues

Development vs Production

Use Environment Variables:

Node.js (.env file):

DOCSDISPATCHER_TOKEN=your_token_here
DOCSDISPATCHER_API_URL=https://api.docs-dispatcher.io

const dd = DocsDispatcher.create({
  token: process.env.DOCSDISPATCHER_TOKEN
})

PHP:

$token = getenv('DOCSDISPATCHER_TOKEN');
$baseUrl = getenv('DOCSDISPATCHER_API_URL') ?: 'https://api.docs-dispatcher.io';

$auth = new BearerTokenAuthentication($token);
$client = new Client($auth, $baseUrl);

Java (Spring Boot application.properties):

docsdispatcher.api.token=${DOCSDISPATCHER_TOKEN}
docsdispatcher.api.url=https://api.docs-dispatcher.io

CORS Issues (Browser/Frontend)

Important: The Docs-Dispatcher API is designed for server-side use only. Never expose your API token in frontend JavaScript as it poses a security risk.

Solution: Create a backend proxy endpoint that calls Docs-Dispatcher from your server.

Getting Help

Before Asking for Help

✅ Check this troubleshooting guide
✅ Review API documentation
✅ Search GitLab issues
✅ Enable debug logging
✅ Test with API validation endpoint

When Reporting Issues

Include the following information:

SDK version: Check package.json, composer.json, or pom.xml
API version: Check response headers or dashboard
Error message: Full error output
Code snippet: Minimal reproducible example
Debug logs: With sensitive data redacted
Environment: OS, runtime version (Node.js, PHP, Java)

Support Channels

GitLab Issues:

Email Support: [email protected]

Documentation:

API Status: status.docs-dispatcher.io

Next Steps

SDK Documentation

Node.js | PHP | Java

Learn from Examples

Recipes & Use Cases

Provider Configuration

Service Providers

Authentication Guide

Authentication

PreviousJava SDK NextCommon Errors

Last updated 5 days ago

hashtagAuthentication Errors

hashtagInvalid Token (401 Unauthorized)

hashtagExpired Token

hashtagMissing Authentication

hashtagValidation Errors

hashtagMissing Required Parameters (400 Bad Request)

hashtagInvalid Data Types

hashtagTemplate Not Found (404 Not Found)

hashtagNetwork and Connection Issues

hashtagConnection Timeout

hashtagSSL/TLS Certificate Errors

hashtagRate Limiting (429 Too Many Requests)

hashtagInstallation Problems

hashtagPackage Manager Errors

hashtagVersion Compatibility Issues

hashtagCommon Mistakes

hashtagWrong Service Enum

hashtagMissing Config for Provider

hashtagIncorrect Response Format

hashtagDebug Logging

hashtagNode.js

hashtagPHP

hashtagJava

hashtagEnvironment-Specific Issues

hashtagDevelopment vs Production

hashtagCORS Issues (Browser/Frontend)

hashtagGetting Help

hashtagBefore Asking for Help

hashtagWhen Reporting Issues

hashtagSupport Channels

hashtagNext Steps

Authentication Errors

Invalid Token (401 Unauthorized)

Expired Token

Missing Authentication

Validation Errors

Missing Required Parameters (400 Bad Request)

Invalid Data Types

Template Not Found (404 Not Found)

Network and Connection Issues

Connection Timeout

SSL/TLS Certificate Errors

Rate Limiting (429 Too Many Requests)

Installation Problems

Package Manager Errors

Version Compatibility Issues

Common Mistakes

Wrong Service Enum

Missing Config for Provider

Incorrect Response Format

Debug Logging

Node.js

PHP

Java

Environment-Specific Issues

Development vs Production

CORS Issues (Browser/Frontend)

Getting Help

Before Asking for Help

When Reporting Issues

Support Channels

Next Steps