Docs

API Documentation

Version 1.0.0

DataWise Document Exchange

API v1.0.0

Error Reference

Error Handling

All error responses include a status code, error code, and descriptive message to help you diagnose and resolve issues quickly.

Error Response Format

When an error occurs, the API returns a JSON response with the following structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      "field": "fieldName",
      "additionalInfo": "..."
    },
    "correlationId": "a1b2c3d4e5f6",
    "timestamp": "2025-10-08T10:30:00.000Z"
  }
}

Response Headers:
X-Correlation-Id: a1b2c3d4e5f6
Content-Type: application/json

code: Machine-readable error code for programmatic handling

message: Detailed description of the error

details: Additional error-specific information (optional)

correlationId: Unique identifier for tracking this error (12 characters)

timestamp: ISO 8601 timestamp when the error occurred

Error Codes

Error Code	HTTP Status	Message	Solution
AUTH_NO_API_KEY	401	Unauthorized!! No api key provided	Include the Authorization header with your API key
AUTH_INVALID_API_KEY	401	Unauthorized!! Invalid api key	Verify your API key is correct and has not been regenerated
AUTH_APP_NOT_ACTIVE	403	Unauthorized!! App is not active	Check your application status in the dashboard and ensure it is active

Error Code	HTTP Status	Message	Solution
VALIDATION_NO_OUTPUT_FORMAT	400	No output format was provided	Include ddx_outputFormat parameter with value ``docx`` or ``pdf``
VALIDATION_INVALID_IMAGE_FORMAT	400	For Images you must be upload the file or the URL of the image	Provide either a file upload or a valid URL for image parameters
VALIDATION_INVALID_ESIGN_CONFIG	400	The ddxE_signers property must be an array of signers	Ensure ddxE_signers is a valid JSON array with signer objects

Error Code	HTTP Status	Message	Solution
PAYMENT_INSUFFICIENT_FUNDS	402	Not enough funds in account	Add funds to your account or enable auto-recharge
PAYMENT_CHARGE_FAILED	402	Payment charge failed	Verify payment method is valid and has sufficient funds

Error Code	HTTP Status	Message	Solution
PROCESSING_DOCUMENT_GENERATION_FAILED	500	Failed to generate document	Check template syntax and data format. Contact support if issue persists
PROCESSING_PDF_CONVERSION_FAILED	500	Failed to convert document to PDF	Verify document format is compatible. Try reducing file size or complexity
PROCESSING_MERGE_FAILED	500	Failed to merge documents	Ensure all documents are in compatible formats and not corrupted
PROCESSING_ESIGN_FAILED	500	Failed to process e-signature request	Verify signer configuration and email addresses. Check e-signature service status

Error Code	HTTP Status	Message	Solution
INTERNAL_SERVER_ERROR	500	An unexpected error occurred	Retry the request. If issue persists, contact support
SERVICE_UNAVAILABLE	503	Service temporarily unavailable	Wait a few moments and retry the request
RATE_LIMIT_EXCEEDED	429	Too many requests	Reduce request frequency or contact support for higher limits
TIMEOUT	504	Request timeout	Reduce file size or complexity and retry

Common Issues & Solutions

Error Handling Best Practices

Client-Side Handling

try {
  const response = await fetch(url, options);
  const data = await response.json();

  if (!response.ok && data.error) {
    // Save correlation ID for debugging
    const correlationId = data.error.correlationId;
    console.error('Error:', correlationId, data.error.message);

    switch(data.error.code) {
      case 'AUTH_NO_API_KEY':
        // Handle missing API key
        break;
      case 'PAYMENT_INSUFFICIENT_FUNDS':
        // Alert user to add funds
        const { balance, required } = data.error.details;
        break;
      // Add other validation error handling here
      default:
        // Generic error handling with correlation ID
        alert(`Error: ${data.error.message}\nID: ${correlationId}`);
    }
  }
} catch (error) {
  // Network or parsing error
  console.error('Request failed:', error);
}

Retry Logic

async function apiCallWithRetry(
  url, options, maxRetries = 3
) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

      // Retry on server errors and rate limits
      if (response.status === 429 ||
          response.status === 503 ||
          response.status === 504) {
        if (i < maxRetries - 1) {
          // Wait with exponential backoff before retry
          await new Promise(r =>
            setTimeout(r, 1000 * Math.pow(2, i))
          );
          continue;
        }
        // Last attempt, return error response
        return await response.json();
      }

      return await response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Debugging Tips

Save the Correlation ID

Every error includes a unique correlationId. Save this when contacting support to help us quickly locate the exact error in our logs.

Validate JSON

Ensure JSON parameters like ddxE_signers and #loops are properly formatted

Test with Preview Mode

Use ddxE_signPreview=true to test e-signature flow without sending emails

Monitor Dashboard Logs

Check your application logs in the dashboard for detailed error information

Use Minimal Test Case

Start with a simple template and gradually add complexity to isolate issues

Need Additional Help?

If you are encountering an error not listed here or need assistance debugging an issue, please contact our support team with the correlation ID from the error response. This unique identifier helps us quickly locate the exact error in our system logs and provide faster assistance.