Troubleshooting

Common issues, solutions, and debugging tips for the Referral Partner API integration.

Authentication Issues

401 Unauthorized - Invalid API Key

Symptoms:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided"
  }
}

Common Causes:

1. Using wrong API key (test vs production)
2. API key not in Authorization header
3. Malformed Authorization header
4. Expired or revoked API key

Solutions:

Check environment:

# Sandbox
https://api.sandbox.debitura.com

# Production
https://api.debitura.com

Verify header format:

curl https://api.debitura.com/v1/referral-partners/ping \
  -H "Authorization: Bearer deb_live_your_key_here"
  # Note: "Bearer" with capital B, space before key

Test your key:

curl https://api.debitura.com/v1/referral-partners/ping \
  -H "Authorization: Bearer YOUR_KEY" \
  -v

403 Forbidden - Insufficient Permissions

Symptoms:

{
  "error": {
    "type": "permission_error",
    "message": "Your API key does not have permission to perform this action"
  }
}

Common Causes:

1. Using partner API key to access client-specific resources
2. Bearer token lacks required scope
3. API key revoked or suspended

Solutions:

For client operations, use bearer token:

# Wrong - Using partner API key
curl https://api.debitura.com/v1/cases \
  -H "Authorization: Bearer deb_live_partner_key"

# Correct - Using client bearer token
curl https://api.debitura.com/v1/cases \
  -H "Authorization: Bearer tok_live_client_token"

Contact support if:

• Your API key should have access
• Bearer token was just issued
• Permissions recently changed

Client Linking Issues

409 Conflict - Client Already Exists

Symptoms:

{
  "error": {
    "type": "conflict_error",
    "conflict_type": "existing_direct_customer",
    "details": {
      "client_id": "cli_abc123",
      "can_claim": false
    }
  }
}

Solutions:

Check if claimable:

if (error.response.status === 409) {
  const { can_claim, client_id } = error.response.data.error.details;

  if (can_claim) {
    // Attempt to claim
    const claimed = await claimClient(client_id);
  } else {
    // Contact support or show message to user
    console.log('Client already exists in Debitura system');
  }
}

See also: Workflow: Handle 409 Conflicts

400 Bad Request - Invalid Client Data

Symptoms:

{
  "error": {
    "type": "validation_error",
    "message": "Invalid country code",
    "field": "country"
  }
}

Common Causes:

1. Invalid country code format
2. Missing required fields
3. Invalid email format
4. VAT number format incorrect

Solutions:

Use ISO 3166-1 alpha-2 country codes:

// Wrong
country: "Denmark"  // Full name
country: "DNK"      // Alpha-3 code

// Correct
country: "DK"       // Alpha-2 code

Validate email addresses:

function isValidEmail(email: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

Check required fields:

const requiredFields = {
  external_id: 'your_customer_id',
  company_name: 'Company Name',
  country: 'DK',
  email: 'contact@company.com',
  onboarding_type: 'api_only'
};

Case Creation Issues

400 Bad Request - Invalid Case Data

Symptoms:

{
  "error": {
    "type": "validation_error",
    "message": "Amount must be positive",
    "field": "amount.value"
  }
}

Common Causes:

1. Invalid amount (negative, zero, or too large)
2. Invalid currency code
3. Invalid date format
4. Missing debtor information

Solutions:

Validate amount:

// Amount must be positive integer (in minor units)
amount: {
  value: 5000,      // €50.00 (in cents)
  currency: "EUR"   // ISO 4217 currency code
}

Use ISO 8601 date format:

// Wrong
due_date: "01/15/2024"     // US format
due_date: "15-01-2024"     // European format

// Correct
due_date: "2024-01-15"     // ISO 8601

Validate currency codes:

// Use ISO 4217 codes
const validCurrencies = ['EUR', 'DKK', 'SEK', 'NOK', 'GBP', 'USD'];

401 Unauthorized - Bearer Token Invalid

Symptoms:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid bearer token"
  }
}

Common Causes:

1. Using partner API key instead of bearer token
2. Bearer token expired or revoked
3. Client relationship terminated
4. Typo in token

Solutions:

Verify you're using bearer token:

// Check token prefix
if (token.startsWith('deb_')) {
  console.error('Using partner API key instead of bearer token');
}
if (token.startsWith('tok_')) {
  console.log('Correct: Using bearer token');
}

Refresh bearer token:

GET /v1/referral-partners/clients/{client_id}/token

Rotate if compromised:

POST /v1/referral-partners/clients/{client_id}/rotate-token

White-Label Onboarding Issues

Onboarding Link Doesn't Work

Symptoms:

• Customer reports broken link
• 404 or expired page

Common Causes:

1. Link expired (7 days)
2. Onboarding already completed
3. Onboarding cancelled
4. Typo in URL

Solutions:

Check onboarding status:

GET /v1/referral-partners/clients/{client_id}/onboarding-status

Resend link if expired:

POST /v1/referral-partners/clients/{client_id}/resend-onboarding

Restart if cancelled:

POST /v1/referral-partners/clients/{client_id}/restart-onboarding

Webhook Not Received After Onboarding

Symptoms:

• Customer completed onboarding
• No webhook notification received
• Bearer token missing

Common Causes:

1. Webhook URL not configured
2. Webhook endpoint returning errors
3. SSL certificate issues
4. Network/firewall blocking

Solutions:

Verify webhook configuration:

GET /v1/referral-partners/settings/white-label

Check webhook endpoint:

# Test your endpoint responds correctly
curl -X POST https://yourplatform.com/webhooks/debitura \
  -H "Content-Type: application/json" \
  -d '{"event":"test","data":{}}'

Requirements for webhook endpoint:

• Must be HTTPS
• Must return 2xx status code
• Should respond within 5 seconds
• Valid SSL certificate

Manually retrieve bearer token:

GET /v1/referral-partners/clients/{client_id}/token

Revenue and Billing Issues

Commission Seems Incorrect

Symptoms:

• Expected commission doesn't match actual
• Cases missing from revenue report
• Commission rate appears wrong

Common Causes:

1. Case not attributed to your partnership
2. Collection not yet completed
3. Wrong commission rate applied
4. Partial payment scenario

Solutions:

Check case attribution:

GET /v1/cases/{case_id}/attribution

Verify collection status:

GET /v1/cases/{case_id}

Review commission calculation:

// Commission = Debitura Fee × Your Rate
const debituraFee = collectedAmount * 0.25; // 25% fee
const yourCommission = debituraFee * 0.20;  // 20% rate

Check for adjustments:

GET /v1/referral-partners/revenue/adjustments

Missing Cases in Attribution

Symptoms:

• Cases created but not attributed
• Attribution rate lower than expected

Common Causes:

1. Case created directly (not via bearer token)
2. Client not linked when case created
3. Bearer token not used correctly
4. Client relationship changed

Solutions:

Ensure bearer token usage:

// Always use client's bearer token when creating cases
const headers = {
  Authorization: `Bearer ${clientBearerToken}`, // Not partner API key
  'Content-Type': 'application/json'
};

Monitor attribution rate:

GET /v1/referral-partners/analytics/attribution

Set up alerts:

{
  "alerts": {
    "low_attribution_rate": {
      "enabled": true,
      "threshold": 0.95
    }
  }
}

Network and Performance Issues

Timeout Errors

Symptoms:

Error: Request timeout

Common Causes:

1. Network connectivity issues
2. Large request payload
3. Server temporarily unavailable
4. Client-side timeout too short

Solutions:

Increase timeout:

const response = await axios.post(url, data, {
  timeout: 30000 // 30 seconds
});

Implement retry logic:

async function retryRequest(fn, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === retries - 1) throw error;
      await sleep(1000 * Math.pow(2, i)); // Exponential backoff
    }
  }
}

Check API status: Visit: https://status.debitura.com

Rate Limiting

Symptoms:

{
  "error": {
    "type": "rate_limit_error",
    "message": "Too many requests",
    "retry_after": 60
  }
}

Rate Limits:

• 1000 requests per hour per API key
• 100 requests per minute per API key
• Burst limit: 20 requests per second

Solutions:

Implement rate limiting:

const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 50, // 50 requests per minute (safety margin)
});

app.use('/api/debitura', limiter);

Respect Retry-After header:

if (error.response.status === 429) {
  const retryAfter = error.response.headers['retry-after'];
  await sleep(retryAfter * 1000);
  // Retry request
}

Use batch operations:

// Instead of creating clients one by one
// Batch create when possible (if endpoint supports it)

Debugging Tips

Enable Debug Logging

Node.js:

import axios from 'axios';

axios.interceptors.request.use(request => {
  console.log('Request:', {
    method: request.method,
    url: request.url,
    headers: request.headers,
    data: request.data
  });
  return request;
});

axios.interceptors.response.use(
  response => {
    console.log('Response:', {
      status: response.status,
      data: response.data
    });
    return response;
  },
  error => {
    console.error('Error:', {
      status: error.response?.status,
      data: error.response?.data
    });
    return Promise.reject(error);
  }
);

Test in Sandbox First

Always test in sandbox before production:

const baseUrl = process.env.NODE_ENV === 'production'
  ? 'https://api.debitura.com'
  : 'https://api.sandbox.debitura.com';

Verify SSL Certificates

Ensure your webhook endpoint has valid SSL:

# Test SSL certificate
openssl s_client -connect yourplatform.com:443 -servername yourplatform.com

Monitor Webhook Deliveries

Check webhook delivery logs:

GET /v1/referral-partners/webhooks/deliveries

Response:

{
  "deliveries": [
    {
      "delivery_id": "del_abc123",
      "event": "client.onboarding_completed",
      "url": "https://yourplatform.com/webhooks/debitura",
      "status_code": 200,
      "delivered_at": "2024-01-15T10:00:00Z",
      "attempts": 1
    }
  ]
}

Getting Help

Before Contacting Support

Gather this information:

1. Request Details:

   • Request ID (from response headers)
   • Timestamp
   • Endpoint called
   • HTTP method

2. Error Information:

   • Full error response
   • Status code
   • Error type and message

3. Context:

   • What you were trying to do
   • Steps to reproduce
   • Expected vs actual behavior

Contact Support

Email: partners@debitura.com

Include:

• Partner ID
• Client ID (if applicable)
• Case ID (if applicable)
• Request/Response examples
• Detailed description

Response Times:

• Critical issues: 2-4 hours
• High priority: 8-24 hours
• Normal priority: 24-48 hours

Useful Resources

• API Status: https://status.debitura.com
• API Reference: https://docs.debitura.com/api
• Partner Portal: https://partners.debitura.com
• Changelog: https://docs.debitura.com/changelog

Common Error Reference

Status	Error Type	Common Cause	Solution
400	validation_error	Invalid request data	Check request format
401	authentication_error	Invalid credentials	Verify API key/token
403	permission_error	Insufficient permissions	Use correct token type
404	not_found	Resource doesn't exist	Verify resource ID
409	conflict_error	Resource conflict	Handle conflict appropriately
429	rate_limit_error	Too many requests	Implement rate limiting
500	internal_error	Server error	Retry, contact support
503	service_unavailable	Temporary outage	Check status page, retry

Next Steps

• Start Here - Overview of referral partnerships
• Integration Examples - Code samples
• API Reference - Complete API documentation